@tangle-network/agent-integrations 0.73.0 → 0.74.0

package/dist/types-BSDXGSi5.js

@@ -0,0 +1,263 @@
+//#region src/connectors/types.ts
+/** Thrown by `executeMutation` when upstream rejects on CAS — caught and
+*  rewrapped by MutationGuard. */
+var ResourceContention = class extends Error {
+	alternatives;
+	currentState;
+	name = "ResourceContention";
+	constructor(message, alternatives = [], currentState) {
+		super(message);
+		this.alternatives = alternatives;
+		this.currentState = currentState;
+	}
+};
+/** Thrown when the connector finds the user's grant has been revoked or the
+*  access token is no longer valid AND refresh failed — reconnecting fixes it.
+*  Surfaces to the UI as "Reconnect required". Carries optional structured
+*  `{status, reason, body}` so the platform can confirm a 401/403 really is a
+*  credential reason before flipping the connection to reconnect_required. */
+var CredentialsExpired = class extends Error {
+	dataSourceId;
+	name = "CredentialsExpired";
+	status;
+	reason;
+	body;
+	constructor(message, dataSourceId, init) {
+		super(message);
+		this.dataSourceId = dataSourceId;
+		this.status = init?.status;
+		this.reason = init?.reason;
+		this.body = init?.body;
+	}
+};
+/** Thrown when the provider rejects the call for a configuration or permission
+*  reason that reconnecting the credential CANNOT fix — the API isn't enabled
+*  for the project (`accessNotConfigured`), a required scope is missing
+*  (`insufficientPermissions`), or the resource is forbidden
+*  (`PERMISSION_DENIED`). Distinct from CredentialsExpired so the platform
+*  surfaces "fix the project/scope" instead of sending the user into an
+*  unresolvable reconnect loop. */
+var ProviderConfigError = class extends Error {
+	dataSourceId;
+	name = "ProviderConfigError";
+	status;
+	reason;
+	body;
+	constructor(message, dataSourceId, init) {
+		super(message);
+		this.dataSourceId = dataSourceId;
+		this.status = init.status;
+		this.reason = init.reason;
+		this.body = init.body;
+	}
+};
+/** Thrown when the provider throttles the call (quota / rate limit). Gmail and
+*  Calendar surface daily/per-user limits as HTTP 403 with a quota `reason`
+*  (`rateLimitExceeded`/`dailyLimitExceeded`/`userRateLimitExceeded`), NOT 429
+*  — so it is classified by reason, not status, and must never read as a
+*  credential failure. The message includes "rate limit" so a platform that
+*  only inspects the message still routes it to rate-limited. */
+var ProviderRateLimited = class extends Error {
+	dataSourceId;
+	name = "ProviderRateLimited";
+	status;
+	reason;
+	body;
+	retryAfterMs;
+	constructor(message, dataSourceId, init) {
+		super(message);
+		this.dataSourceId = dataSourceId;
+		this.status = init.status;
+		this.reason = init.reason;
+		this.body = init.body;
+		this.retryAfterMs = init.retryAfterMs;
+	}
+};
+/** Thrown when the provider settles a call with a non-2xx status that is not
+*  a credential, permission or rate-limit failure: a 400 naming a bad field, a
+*  404, a 409, or a 5xx. Carries `{status, reason, body}` so the platform
+*  answers a refusal as a refusal (a 4xx with the provider's message) instead
+*  of a gateway fault, and keeps the provider's own error code as `reason`. */
+var ProviderRequestError = class extends Error {
+	dataSourceId;
+	name = "ProviderRequestError";
+	status;
+	reason;
+	body;
+	constructor(message, dataSourceId, init) {
+		super(message);
+		this.dataSourceId = dataSourceId;
+		this.status = init.status;
+		this.reason = init.reason;
+		this.body = init.body;
+	}
+};
+/** Thrown before any provider request when a caller's argument breaks the
+*  capability's declared contract: a value that fails its `pattern`, or one the
+*  provider would refuse with a misleading answer (a commit sha where a branch
+*  name belongs reads back as "Branch not found"). `field` names the argument,
+*  and the message says what to pass instead. `status` is 400 so a platform
+*  classifier answers it as a settled refusal: the same arguments fail again. */
+var InvalidCapabilityArgument = class extends Error {
+	field;
+	name = "InvalidCapabilityArgument";
+	status = 400;
+	reason = "invalid_argument";
+	constructor(message, field) {
+		super(message);
+		this.field = field;
+	}
+};
+/** Validate the static connector manifest before a provider registers it.
+*  This catches the expensive mistakes early: duplicate capability names,
+*  mutation capabilities without CAS, authoritative fire-and-forget writes,
+*  and invalid rate-limit specs. */
+function validateConnectorManifest(manifest) {
+	const issues = [];
+	if (!manifest.kind.trim()) issues.push({
+		path: "kind",
+		message: "kind is required"
+	});
+	if (!manifest.displayName.trim()) issues.push({
+		path: "displayName",
+		message: "displayName is required"
+	});
+	const consistencyModels = /* @__PURE__ */ new Set([
+		"authoritative",
+		"cache",
+		"advisory"
+	]);
+	if (!consistencyModels.has(manifest.defaultConsistencyModel)) issues.push({
+		path: "defaultConsistencyModel",
+		message: "unsupported consistency model"
+	});
+	validateAuthSpec(manifest.auth, issues);
+	const seen = /* @__PURE__ */ new Set();
+	for (const [index, capability] of manifest.capabilities.entries()) {
+		const path = `capabilities[${index}]`;
+		if (!capability.name.trim()) issues.push({
+			path: `${path}.name`,
+			message: "capability name is required"
+		});
+		if (seen.has(capability.name)) issues.push({
+			path: `${path}.name`,
+			message: `duplicate capability name: ${capability.name}`
+		});
+		seen.add(capability.name);
+		if (capability.consistencyModel !== void 0 && !consistencyModels.has(capability.consistencyModel)) issues.push({
+			path: `${path}.consistencyModel`,
+			message: "unsupported consistency model"
+		});
+		if (capability.class === "mutation") {
+			if (!capability.cas) issues.push({
+				path: `${path}.cas`,
+				message: "mutation capability must declare a CAS strategy"
+			});
+			if ((capability.consistencyModel ?? manifest.defaultConsistencyModel) === "authoritative" && capability.cas === "none") issues.push({
+				path: `${path}.cas`,
+				message: "authoritative mutations cannot use cas=\"none\""
+			});
+		}
+	}
+	if (manifest.rateLimit) {
+		if (!Number.isFinite(manifest.rateLimit.requests) || manifest.rateLimit.requests <= 0) issues.push({
+			path: "rateLimit.requests",
+			message: "rateLimit.requests must be positive"
+		});
+		if (!Number.isFinite(manifest.rateLimit.windowMs) || manifest.rateLimit.windowMs <= 0) issues.push({
+			path: "rateLimit.windowMs",
+			message: "rateLimit.windowMs must be positive"
+		});
+	}
+	return {
+		ok: issues.length === 0,
+		issues
+	};
+}
+function validateAuthSpec(auth, issues) {
+	if (auth.kind === "oauth2") {
+		validateOAuth2AuthSpec(auth, issues, "auth");
+		return;
+	}
+	if (auth.kind !== "one_of") return;
+	if (auth.options.length < 2) issues.push({
+		path: "auth.options",
+		message: "one_of auth must declare at least two options"
+	});
+	if (!new Set(auth.options.map((option) => option.kind)).has(auth.preferred)) issues.push({
+		path: "auth.preferred",
+		message: "one_of preferred auth must match an option kind"
+	});
+	for (const [index, option] of auth.options.entries()) if (option.kind === "oauth2") validateOAuth2AuthSpec(option, issues, `auth.options[${index}]`);
+}
+function validateOAuth2AuthSpec(auth, issues, path) {
+	if ((auth.grantType ?? "authorization_code") === "authorization_code" && !auth.authorizationUrl?.trim()) issues.push({
+		path: `${path}.authorizationUrl`,
+		message: "authorization_code grant requires authorizationUrl"
+	});
+	if (auth.pkce !== void 0 && auth.pkce !== "required" && auth.pkce !== "supported" && auth.pkce !== "unsupported") issues.push({
+		path: `${path}.pkce`,
+		message: "pkce must be required, supported, or unsupported"
+	});
+	for (const [key, spec] of Object.entries(auth.urlTemplateMetadata ?? {})) {
+		if (spec.kind !== "base-url" && spec.kind !== "path-segment") {
+			issues.push({
+				path: `${path}.urlTemplateMetadata.${key}.kind`,
+				message: "OAuth URL metadata kind must be base-url or path-segment"
+			});
+			continue;
+		}
+		const placeholder = `{${key}}`;
+		if (!auth.authorizationUrl?.includes(placeholder) && !auth.tokenUrl.includes(placeholder)) issues.push({
+			path: `${path}.urlTemplateMetadata.${key}`,
+			message: `OAuth URL metadata is unused; add ${placeholder} to an OAuth endpoint`
+		});
+		if (spec.kind === "base-url") {
+			if (!spec.requirePublicHttps && !spec.allowedBaseUrls?.length && !spec.allowedBaseUrlSuffixes?.length) issues.push({
+				path: `${path}.urlTemplateMetadata.${key}`,
+				message: "OAuth base URL metadata requires an allowlist or public HTTPS policy"
+			});
+			for (const suffix of spec.allowedBaseUrlSuffixes ?? []) if (!/^\.[a-z0-9.-]+$/i.test(suffix)) issues.push({
+				path: `${path}.urlTemplateMetadata.${key}.allowedBaseUrlSuffixes`,
+				message: "OAuth base URL hostname suffixes must start with a dot"
+			});
+		} else for (const endpoint of [auth.authorizationUrl, auth.tokenUrl]) if (endpoint?.includes(placeholder) && !isOAuthPathSegmentPlaceholder(endpoint, placeholder)) issues.push({
+			path: `${path}.urlTemplateMetadata.${key}`,
+			message: `OAuth path metadata ${placeholder} must occupy a complete URL path segment`
+		});
+	}
+	if (auth.tokenClientAuthMethod !== void 0 && auth.tokenClientAuthMethod !== "none" && auth.tokenClientAuthMethod !== "client_secret_post" && auth.tokenClientAuthMethod !== "client_secret_basic") issues.push({
+		path: `${path}.tokenClientAuthMethod`,
+		message: "tokenClientAuthMethod must be none, client_secret_post, or client_secret_basic"
+	});
+	if ((auth.tokenClientAuthMethod ?? "client_secret_post") !== "none" && !auth.clientSecretEnv?.trim()) issues.push({
+		path: `${path}.clientSecretEnv`,
+		message: "confidential OAuth clients require clientSecretEnv"
+	});
+	for (const header of Object.keys(auth.tokenRequestHeaders ?? {})) if (header.toLowerCase() === "authorization" || header.toLowerCase() === "content-type") issues.push({
+		path: `${path}.tokenRequestHeaders.${header}`,
+		message: "tokenRequestHeaders cannot override Authorization or Content-Type"
+	});
+}
+function isOAuthPathSegmentPlaceholder(template, placeholder) {
+	const schemeIndex = template.indexOf("://");
+	const rootEnd = schemeIndex >= 0 ? schemeIndex + 3 : template.startsWith("{") ? template.indexOf("}") + 1 : 0;
+	const pathStart = template.indexOf("/", rootEnd);
+	const queryStart = template.search(/[?#]/);
+	let cursor = 0;
+	while (true) {
+		const index = template.indexOf(placeholder, cursor);
+		if (index < 0) return true;
+		const end = index + placeholder.length;
+		if (pathStart < 0 || index < pathStart || queryStart >= 0 && index >= queryStart || template[index - 1] !== "/" || end < template.length && template[end] !== "/" && template[end] !== "?" && template[end] !== "#") return false;
+		cursor = end;
+	}
+}
+function assertValidConnectorManifest(manifest) {
+	const result = validateConnectorManifest(manifest);
+	if (!result.ok) throw new Error(`Invalid connector manifest ${manifest.kind || "<unknown>"}: ${result.issues.map((issue) => `${issue.path}: ${issue.message}`).join("; ")}`);
+}
+//#endregion
+export { ProviderRequestError as a, validateConnectorManifest as c, ProviderRateLimited as i, InvalidCapabilityArgument as n, ResourceContention as o, ProviderConfigError as r, assertValidConnectorManifest as s, CredentialsExpired as t };
+
+//# sourceMappingURL=types-BSDXGSi5.js.map

package/dist/types-BSDXGSi5.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-BSDXGSi5.js","names":[],"sources":["../src/connectors/types.ts"],"sourcesContent":["/**\n * Connector primitives — the contract a concrete first-party integration\n * (Google Calendar, HubSpot, Stripe, ...) implements. Lower level than the\n * hub-side `IntegrationProvider` interface from `../index.ts`: a single\n * `IntegrationProvider` typically wraps several connectors (e.g., a\n * \"first-party\" provider that lists all your shipped connectors as a\n * single catalog).\n *\n * Layering:\n *\n *   IntegrationHub                                — vendor-neutral facade (../index.ts)\n *     ↓\n *   IntegrationProvider                           — one per gateway or first-party provider\n *     ↓\n *   ConnectorAdapter (this file)                  — one per integration (Google Calendar, ...)\n *     ↓\n *   upstream HTTP API                             — vendor SDK / fetch / OAuth\n *\n * Three load-bearing decisions encoded here:\n *\n * 1. Capabilities are typed (`read` vs `mutation`). Every mutation MUST\n *    declare a CAS strategy. Conflict resolution is the SDK's job, not the\n *    connector's. `validateConnectorManifest()` rejects unsafe manifests\n *    before a connector is registered.\n *\n * 2. ConsistencyModel pins what the rest of the system can assume:\n *      authoritative → the source IS the truth (Calendar, payments)\n *      cache         → we mirror with TTL and may serve stale (price list)\n *      advisory      → informational only (FAQ doc)\n *    Agent planners can (and should) refuse to promise outcomes based on\n *    `cache`/`advisory` data without a live `authoritative` confirmation.\n *\n * 3. Capabilities surface to the calling agent's tool registry by\n *    transformation, not by hand-wiring. Adding a connector automatically\n *    expands the agent's toolbelt for that specific user without touching\n *    the prompt or runner.\n */\n\n/** Minimal JSON-schema shape used for capability arg validation. We\n *  intentionally don't pull `@types/json-schema` — most consumers already\n *  declare parameters as `Record<string, unknown>` and the\n *  shape is whatever the LLM SDK's structured-output expects. Keep the\n *  contract loose at the boundary; tighten via runtime zod where needed. */\nexport type CapabilityParameterSchema = Record<string, unknown>\n\n/** What the rest of the system is allowed to assume about freshness. */\nexport type ConsistencyModel = 'authoritative' | 'cache' | 'advisory'\n\n/** Capability classes. `read` is safe to retry; `mutation` must go through\n *  MutationGuard (CAS + idempotency). `subscribe` is reserved for future\n *  push-driven sources (webhook callbacks) and is not yet wired. */\nexport type CapabilityClass = 'read' | 'mutation' | 'subscribe'\n\n/** Compare-and-swap strategy a mutation uses to detect conflicts. */\nexport type CASStrategy =\n  /** Upstream returns an etag/sequence on read, accepts If-Match on write\n   *  (Google Calendar, GitHub, GDocs revision_id). The connector returns\n   *  412 / Precondition Failed on conflict; the SDK maps to ResourceContention. */\n  | 'etag-if-match'\n  /** Upstream guarantees exactly-once-per-key (Stripe, idempotent webhooks).\n   *  The SDK passes the idempotency key through; no etag check. */\n  | 'native-idempotency'\n  /** No upstream concurrency control. Connector MUST do read-then-write\n   *  and verify nothing changed in-between (best-effort). Suitable only\n   *  for low-contention single-user resources; rejected for any\n   *  consistencyModel='authoritative' write that may race. */\n  | 'optimistic-read-verify'\n  /** Source is not contended (e.g. logging, telemetry). Mutations are\n   *  fire-and-forget. Marks the capability as not eligible for\n   *  authoritative writes. */\n  | 'none'\n\nexport interface CapabilityRead {\n  name: string\n  class: 'read'\n  description: string\n  /** JSON-schema for the tool args the agent passes when invoking. */\n  parameters: CapabilityParameterSchema\n  /** Override the connector default when this action has a different consistency guarantee. */\n  consistencyModel?: ConsistencyModel\n  /** Optional: declare which scopes (per the connector manifest) this\n   *  capability requires. The capability is hidden from the agent's\n   *  tool registry if the user's grant didn't include them. */\n  requiredScopes?: string[]\n}\n\nexport interface CapabilityMutation {\n  name: string\n  class: 'mutation'\n  description: string\n  parameters: CapabilityParameterSchema\n  /** Override the connector default when this action has a different consistency guarantee. */\n  consistencyModel?: ConsistencyModel\n  /** Mandatory: how does the connector guarantee at-most-once + conflict-detect? */\n  cas: CASStrategy\n  /** True for capabilities that affect resources outside the calling user\n   *  (e.g. booking against a shared calendar, charging a card). The agent's\n   *  planner treats these specially: requires explicit caller confirmation\n   *  before the call. */\n  externalEffect: boolean\n  requiredScopes?: string[]\n}\n\nexport type Capability = CapabilityRead | CapabilityMutation\n\n/** OAuth2 scope catalog the user has granted us, plus arbitrary metadata\n *  the connector pinned at connect-time (calendar id, sheet id, webhook\n *  url, …). `metadata` MUST NOT contain secrets — those go in the\n *  encrypted credentials envelope. */\nexport interface DataSourceMetadata {\n  scopes: string[]\n  [key: string]: unknown\n}\n\n/** A connected, authenticated, ready-to-call data source for a project.\n *  Persistence shape mirrors the product's connection/source row but normalized — the\n *  encrypted credentials envelope is decrypted at hand-out time and held\n *  in memory only for the duration of the call. */\nexport interface ResolvedDataSource {\n  id: string\n  projectId: string\n  publishedAgentId: string | null\n  kind: string\n  label: string\n  consistencyModel: ConsistencyModel\n  scopes: string[]\n  metadata: Record<string, unknown>\n  /** Unwrapped credentials handed to the connector at call-time. Never\n   *  persisted in this shape; never logged. */\n  credentials: ConnectorCredentials\n  status: 'active' | 'revoked' | 'error'\n}\n\n/** Discriminated union of credential shapes. Connectors that need new\n *  shapes extend this union — `kind` is sealed via the tagged pattern so\n *  TypeScript catches an exhaustiveness gap at compile time. */\nexport type ConnectorCredentials =\n  | { kind: 'oauth2'; accessToken: string; refreshToken?: string; expiresAt?: number }\n  | { kind: 'api-key'; apiKey: string }\n  | { kind: 'custom'; values: Record<string, unknown> }\n  | { kind: 'hmac'; secret: string }\n  | { kind: 'none' }\n\n/** Result of a read capability invocation. */\nexport interface CapabilityReadResult {\n  /** Free-form payload — the connector's data shape. The agent receives\n   *  this as the tool result; planners consume it via JSON-shape contract\n   *  declared in the capability's `parameters` (output schema). */\n  data: unknown\n  /** Optional etag/sequence the caller can reuse for a subsequent CAS\n   *  mutation. */\n  etag?: string\n  /** When this read happened (UTC ms since epoch). */\n  fetchedAt: number\n}\n\n/** Result of a mutation capability invocation. Either committed (with the\n *  resulting etag/sequence so the caller can chain mutations), or\n *  contended (the upstream rejected with a state mismatch — the agent\n *  should re-read and retry, or surface alternatives to the caller). */\nexport type CapabilityMutationResult =\n  | {\n      status: 'committed'\n      data: unknown\n      etagAfter?: string\n      committedAt: number\n      /** True iff this commit was returned from the idempotency store\n       *  rather than executed against upstream. The caller can use this\n       *  to suppress confirmation messages on retry. */\n      idempotentReplay: boolean\n    }\n  | {\n      status: 'conflict'\n      /** Best-effort alternative options the upstream surfaced (e.g.,\n       *  next-available calendar slots after a booking conflict). */\n      alternatives: unknown[]\n      /** The current authoritative state, if the connector could re-read\n       *  cheaply. */\n      currentState?: unknown\n      message: string\n    }\n  | {\n      status: 'rate-limited'\n      /** Wall-clock ms the caller should wait before retrying. The SDK\n       *  computes this from the bucket's refill schedule so the agent\n       *  doesn't have to guess. */\n      retryAfterMs: number\n      message: string\n    }\n\n/** Inputs the SDK passes into the connector's executeRead / executeMutation. */\nexport interface ConnectorInvocation {\n  source: ResolvedDataSource\n  capabilityName: string\n  args: Record<string, unknown>\n  /** Idempotency key the caller (or the SDK's defaulting policy) supplied.\n   *  Always present at the connector boundary — the SDK manufactures one\n   *  if the agent didn't pass one. */\n  idempotencyKey: string\n  /** Optional caller-supplied etag the connector should send as If-Match. */\n  expectedEtag?: string\n  /** Product/session id (if any) for forensic logging. */\n  callSessionId?: string\n  /** Fired by the adapter when it rotates the credentials mid-call (e.g. an\n   *  OAuth access token refreshed on expiry). The host re-encrypts +\n   *  persists the rotated envelope so the next expiry does not force a\n   *  reconnect. Adapters MUST invoke this with the FULL rotated envelope,\n   *  not a partial — the previous refresh token is preserved by the caller's\n   *  refresh logic, not inferred here. */\n  onCredentialsRotated?: (\n    credentials: ConnectorCredentials,\n  ) => Promise<void> | void\n}\n\n/** A single inbound event extracted from a push payload. The webhook\n *  receiver persists one `InboundEvent` row per entry the connector returns. */\nexport interface InboundEvent {\n  eventType: string\n  providerEventId?: string\n  payload: Record<string, unknown>\n}\n\n/** Adapter response from an inbound-webhook dispatch. The receiver persists\n *  every `events[]` entry, then either honors the connector's `response`\n *  override (Slack `url_verification` echo, provider-specific 2xx body) or\n *  defaults to `{status: 200, body: {received: true, count: events.length}}`. */\nexport interface EventHandlerResult {\n  events: InboundEvent[]\n  /** Optional: how to respond to the provider. Stripe wants 200 within\n   *  30s; Slack wants the challenge param echoed. */\n  response?: { status: number; body: unknown; headers?: Record<string, string> }\n}\n\n/**\n * Connector adapter — one per integration kind. Stateless. The SDK holds\n * the persistence + crypto + mutation-guard concerns; the adapter only\n * knows how to talk to its upstream.\n */\nexport interface ConnectorAdapter {\n  /** Manifest entry the registry uses to render UI + validate args. */\n  manifest: ConnectorManifest\n  /**\n   * True when this adapter only receives provider events and must not appear\n   * in public connector or action discovery. Hosts can still register it\n   * explicitly for their inbound route, which preserves its stable kind id.\n   */\n  inboundOnly?: boolean\n  /** Read invocation. Required when manifest.capabilities contains reads.\n   *  Should return whatever shape the capability declared\n   *  in its parameters output schema. */\n  executeRead?(inv: ConnectorInvocation): Promise<CapabilityReadResult>\n  /** Mutation invocation. Required when manifest.capabilities contains mutations.\n   *  Throws ResourceContention on a CAS miss; throws\n   *  any other Error for upstream failures. The MutationGuard wraps this\n   *  with idempotency-key short-circuit + audit logging — adapters do\n   *  NOT manage their own dedup. */\n  executeMutation?(inv: ConnectorInvocation): Promise<CapabilityMutationResult>\n  /** Inbound webhook signature verifier. Called BEFORE handleInboundEvent.\n   *  MUST use constant-time comparison (`crypto.timingSafeEqual`) for any\n   *  HMAC check. The receiver returns 401 on `valid=false` without invoking\n   *  handleInboundEvent. Optional: connectors that don't accept push events\n   *  omit this method and the receiver returns 405 for the kind. */\n  verifySignature?(input: {\n    rawBody: string\n    headers: Record<string, string | string[] | undefined>\n    source: ResolvedDataSource\n  }): { valid: boolean; reason?: string }\n  /** Inbound webhook dispatch. Called AFTER verifySignature passes. The\n   *  adapter parses the provider payload and emits zero-or-more\n   *  `InboundEvent` rows; the receiver persists them as one row each (modulo\n   *  the (dataSourceId, providerEventId) dedup unique). The optional\n   *  `response` overrides the receiver's default 200 (Slack `url_verification`\n   *  needs to echo the challenge in the body to pass Slack's app-config check). */\n  handleInboundEvent?(input: {\n    source: ResolvedDataSource\n    rawBody: string\n    headers: Record<string, string | string[] | undefined>\n  }): Promise<EventHandlerResult>\n  /** OAuth callback handler — exchanges the auth code for tokens, returns\n   *  the credentials envelope + scopes + metadata. Only present for\n   *  oauth2-style adapters. */\n  exchangeOAuth?(input: {\n    code: string\n    state: string\n    /** Required unless this connector declares PKCE as unsupported. */\n    codeVerifier?: string\n    redirectUri: string\n  }): Promise<{\n    credentials: ConnectorCredentials\n    scopes: string[]\n    metadata: Record<string, unknown>\n  }>\n  /** Refresh access token. Only required for oauth2 adapters with\n   *  short-lived access tokens. */\n  refreshToken?(input: ConnectorCredentials): Promise<ConnectorCredentials>\n  /** Health check — invoked when the user clicks \"Test connection\" in the\n   *  UI. Should perform the cheapest possible read that proves the grant\n   *  is still valid. Returns `{ok: false, reason}` rather than throwing\n   *  for the common case (token expired, scope missing). */\n  test(\n    source: ResolvedDataSource,\n    /** Optional persistence sink for credentials rotated by the health check. */\n    onCredentialsRotated?: (\n      credentials: ConnectorCredentials,\n    ) => Promise<void> | void,\n  ): Promise<{ ok: true } | { ok: false; reason: string }>\n}\n\n/** Static manifest a connector module exports. Drives the UI catalog,\n *  scope display, capability discovery for the agent's tool registry. */\nexport interface ConnectorManifest {\n  /** Stable kind id used as the foreign key in DataSource.kind. */\n  kind: string\n  /** Human label shown in the UI catalog. */\n  displayName: string\n  /** One-paragraph description shown next to the connect button. */\n  description: string\n  /** Auth shape this connector requires. */\n  auth: AuthSpec\n  /** Capability catalog — the agent's tool registry derives ToolDefinition\n   *  entries from this list at request time. */\n  capabilities: Capability[]\n  /** ConsistencyModel default for this kind — overridable per capability and\n   *  per DataSource when an action or instance has a different guarantee. */\n  defaultConsistencyModel: ConsistencyModel\n  /** Connector category for UI grouping. */\n  category:\n    | 'calendar'\n    | 'spreadsheet'\n    | 'crm'\n    | 'doc'\n    | 'webhook'\n    | 'storage'\n    | 'comms'\n    | 'commerce'\n    | 'database'\n    | 'sales-intelligence'\n    | 'market-intelligence'\n    | 'hr'\n    | 'other'\n  /** Optional icon URL or named icon. */\n  icon?: string\n  /** Optional per-kind rate-limit budget. The SDK enforces it inside\n   *  `executeGuardedMutation` and the read path of `/invoke`. Omit to\n   *  leave the connector unrestricted. */\n  rateLimit?: RateLimitSpec\n}\n\n/** Token-bucket budget the SDK enforces against the connector's upstream.\n *  We meter on OUR side rather than letting the upstream reject so a\n *  chatty agent can't burn quota that's shared across customers (almost\n *  every OAuth client is). */\nexport interface RateLimitSpec {\n  /** Max requests per window. */\n  requests: number\n  /** Window in ms. */\n  windowMs: number\n  /** Whether to apply across all DataSources sharing the same OAuth\n   *  client (true; default), or per-DataSource (false). The former\n   *  matches how upstreams meter (per-app), so almost always pick true. */\n  scope?: 'oauth-client' | 'data-source'\n}\n\n/** Source mapping for `OAuth2AuthSpec.tokenMetadata`. A bare string names the\n *  token-response field to capture (capture-if-present). The object form marks\n *  the field `required` so a missing/empty value fails the token exchange loud\n *  rather than silently capturing nothing. */\nexport type TokenMetadataSource = string | { field: string; required?: boolean }\n\n/** How an OAuth token endpoint authenticates this client.\n *\n * Public clients use `none` and send only the client id. OAuth providers\n * otherwise default to `client_secret_post`, which sends both values in the\n * form body. `client_secret_basic` sends an HTTP Basic header instead. */\nexport type OAuth2TokenClientAuthMethod =\n  | 'none'\n  | 'client_secret_post'\n  | 'client_secret_basic'\n\nexport type OAuth2UrlTemplateMetadataSpec =\n  | {\n      /** A complete HTTPS provider base URL, substituted for a URL template\n       *  placeholder such as `{accountUrl}`. */\n      kind: 'base-url'\n      /** Exact provider roots accepted for finite regional endpoint sets. */\n      allowedBaseUrls?: readonly string[]\n      /** HTTPS hostname suffixes accepted for tenant-specific provider roots. */\n      allowedBaseUrlSuffixes?: readonly string[]\n      /** Permit a caller-selected public HTTPS root for self-hosted providers. */\n      requirePublicHttps?: boolean\n    }\n  | {\n      /** One RFC 3986 unreserved path segment. The resolver encodes it and\n       *  rejects separators, dot segments, query data, and fragments. */\n      kind: 'path-segment'\n    }\n\ntype OAuth2AuthSpec = {\n  kind: 'oauth2'\n  /** OAuth2 grant type. Defaults to `'authorization_code'` (the interactive\n   *  3-legged flow). Set `'client_credentials'` for machine-to-machine\n   *  providers (e.g. Paychex) that issue tokens directly from client\n   *  id/secret with no user-facing authorization step — `authorizationUrl`\n   *  is then omitted. */\n  grantType?: 'authorization_code' | 'client_credentials'\n  /** Authorization endpoint URL. Required for the `authorization_code`\n   *  grant; omitted for `client_credentials` (there is no authorize step). */\n  authorizationUrl?: string\n  /** Token endpoint URL. */\n  tokenUrl: string\n  /** Scopes requested in the authorization grant. The user UI shows\n   *  these so the customer knows what's being shared. */\n  scopes: string[]\n  /** Separator used when serializing multiple scopes into the authorization\n   *  URL. OAuth defaults to spaces; Zoho requires comma-delimited scopes. */\n  scopeSeparator?: ' ' | ','\n  /** Provider PKCE posture. Defaults to the host flow policy when omitted. */\n  pkce?: 'required' | 'supported' | 'unsupported'\n  /** Query parameter that receives the OAuth client id on the authorization\n   *  URL. Defaults to `client_id`; TikTok calls this value `client_key`. */\n  authorizationClientIdParam?: string\n  /** Whether the connector supports incremental authorization (Google\n   *  does; many don't). */\n  incremental?: boolean\n  /** Env-var name holding the OAuth client_id. */\n  clientIdEnv: string\n  /** Env-var name holding the OAuth client_secret. Omit only for public\n   *  clients whose tokenClientAuthMethod is `none`. */\n  clientSecretEnv?: string\n  /** Form parameter that receives the client id during token exchange.\n   *  Defaults to `client_id`; TikTok calls this value `client_key`. */\n  tokenClientIdParam?: string\n  /** Form parameter that receives the client secret during token exchange.\n   *  Defaults to `client_secret`. */\n  tokenClientSecretParam?: string\n  /** OAuth client authentication for the authorization-code token exchange.\n   * Defaults to `client_secret_post` for backward compatibility. */\n  tokenClientAuthMethod?: OAuth2TokenClientAuthMethod\n  /** Optional extra params attached to the authorization URL (e.g.,\n   *  Google's `access_type=offline&prompt=consent` to obtain refresh\n   *  tokens). */\n  extraAuthParams?: Record<string, string>\n  /** Rules for metadata placeholders that represent provider roots or path\n   *  segments. Placeholders without a rule remain single DNS labels. */\n  urlTemplateMetadata?: Readonly<Record<string, OAuth2UrlTemplateMetadataSpec>>\n  /** Non-secret headers sent to the token endpoint. Use this for provider\n   *  identification headers such as Reddit's required User-Agent. The runtime\n   *  always owns Authorization and Content-Type. */\n  tokenRequestHeaders?: Record<string, string>\n  /** Whether to send the `scope` query param on the authorization URL.\n   *  Defaults to true. Set false for providers that reject a per-request\n   *  scope and pin scopes app-side (e.g. HelloSign/Dropbox Sign). */\n  sendScopeParam?: boolean\n  /** Declarative capture of provider-specific fields from the OAuth token\n   *  response into the connection's `metadata`, keyed by the connection-metadata\n   *  key to write → the token-response field to read. The counterpart to\n   *  `baseUrl.metadataKey`: providers like Gong return a per-customer host\n   *  (`api_base_url_for_customer`) at token exchange that every later call must\n   *  target, but the standard token parser keeps only the canonical OAuth\n   *  fields and drops the rest. Declaring the mapping here makes `completeAuth`\n   *  persist the value into `metadata` so `baseUrl` resolution finds it. Mark a\n   *  field `required` to fail the exchange loud when it is absent (surfacing the\n   *  break at connect, not first call). Optional and backward-compatible —\n   *  connectors that omit it are unaffected. */\n  tokenMetadata?: Record<string, TokenMetadataSource>\n}\ntype ApiKeyAuthSpec = {\n  kind: 'api-key'\n  /** UI hint shown when collecting the key. */\n  hint: string\n}\ntype SingleAuthSpec = OAuth2AuthSpec | ApiKeyAuthSpec | { kind: 'hmac' } | { kind: 'none' }\n\nexport type AuthSpec =\n  | SingleAuthSpec\n  | {\n      kind: 'one_of'\n      /** Preferred auth kind for setup UI and OAuth-connect flows. */\n      preferred: 'oauth2' | 'api-key'\n      /** Explicit supported auth modes. Do not infer fallback modes. */\n      options: readonly [SingleAuthSpec, SingleAuthSpec, ...SingleAuthSpec[]]\n    }\n\n/** Thrown by `executeMutation` when upstream rejects on CAS — caught and\n *  rewrapped by MutationGuard. */\nexport class ResourceContention extends Error {\n  override readonly name = 'ResourceContention'\n  constructor(\n    message: string,\n    public readonly alternatives: unknown[] = [],\n    public readonly currentState?: unknown,\n  ) {\n    super(message)\n  }\n}\n\n/** Structured HTTP failure detail attached to the typed provider errors below.\n *  The platform classifier reads `status`/`reason` off the thrown instance to\n *  route a 403 by WHY it failed (credential vs config/permission vs quota)\n *  instead of regexing a flattened message. */\nexport interface ProviderHttpErrorInit {\n  /** Upstream HTTP status (e.g. 401, 403, 429). */\n  status: number\n  /** Provider-specific machine reason (e.g. Google's `accessNotConfigured`,\n   *  `dailyLimitExceeded`, `invalid_grant`) — the actionable signal. */\n  reason?: string\n  /** Parsed upstream error body, kept for diagnostics/audit. */\n  body?: unknown\n}\n\n/** Thrown when the connector finds the user's grant has been revoked or the\n *  access token is no longer valid AND refresh failed — reconnecting fixes it.\n *  Surfaces to the UI as \"Reconnect required\". Carries optional structured\n *  `{status, reason, body}` so the platform can confirm a 401/403 really is a\n *  credential reason before flipping the connection to reconnect_required. */\nexport class CredentialsExpired extends Error {\n  override readonly name = 'CredentialsExpired'\n  readonly status?: number\n  readonly reason?: string\n  readonly body?: unknown\n  constructor(\n    message: string,\n    public readonly dataSourceId: string,\n    init?: ProviderHttpErrorInit,\n  ) {\n    super(message)\n    this.status = init?.status\n    this.reason = init?.reason\n    this.body = init?.body\n  }\n}\n\n/** Thrown when the provider rejects the call for a configuration or permission\n *  reason that reconnecting the credential CANNOT fix — the API isn't enabled\n *  for the project (`accessNotConfigured`), a required scope is missing\n *  (`insufficientPermissions`), or the resource is forbidden\n *  (`PERMISSION_DENIED`). Distinct from CredentialsExpired so the platform\n *  surfaces \"fix the project/scope\" instead of sending the user into an\n *  unresolvable reconnect loop. */\nexport class ProviderConfigError extends Error {\n  override readonly name = 'ProviderConfigError'\n  readonly status: number\n  readonly reason?: string\n  readonly body?: unknown\n  constructor(\n    message: string,\n    public readonly dataSourceId: string,\n    init: ProviderHttpErrorInit,\n  ) {\n    super(message)\n    this.status = init.status\n    this.reason = init.reason\n    this.body = init.body\n  }\n}\n\nexport interface ProviderRateLimitedInit extends ProviderHttpErrorInit {\n  /** Wall-clock ms the caller should wait before retrying — resolved from the\n   *  provider's `Retry-After` when one was sent. */\n  retryAfterMs?: number\n}\n\n/** Thrown when the provider throttles the call (quota / rate limit). Gmail and\n *  Calendar surface daily/per-user limits as HTTP 403 with a quota `reason`\n *  (`rateLimitExceeded`/`dailyLimitExceeded`/`userRateLimitExceeded`), NOT 429\n *  — so it is classified by reason, not status, and must never read as a\n *  credential failure. The message includes \"rate limit\" so a platform that\n *  only inspects the message still routes it to rate-limited. */\nexport class ProviderRateLimited extends Error {\n  override readonly name = 'ProviderRateLimited'\n  readonly status: number\n  readonly reason?: string\n  readonly body?: unknown\n  readonly retryAfterMs?: number\n  constructor(\n    message: string,\n    public readonly dataSourceId: string,\n    init: ProviderRateLimitedInit,\n  ) {\n    super(message)\n    this.status = init.status\n    this.reason = init.reason\n    this.body = init.body\n    this.retryAfterMs = init.retryAfterMs\n  }\n}\n\n/** Thrown when the provider settles a call with a non-2xx status that is not\n *  a credential, permission or rate-limit failure: a 400 naming a bad field, a\n *  404, a 409, or a 5xx. Carries `{status, reason, body}` so the platform\n *  answers a refusal as a refusal (a 4xx with the provider's message) instead\n *  of a gateway fault, and keeps the provider's own error code as `reason`. */\nexport class ProviderRequestError extends Error {\n  override readonly name = 'ProviderRequestError'\n  readonly status: number\n  readonly reason?: string\n  readonly body?: unknown\n  constructor(\n    message: string,\n    public readonly dataSourceId: string,\n    init: ProviderHttpErrorInit,\n  ) {\n    super(message)\n    this.status = init.status\n    this.reason = init.reason\n    this.body = init.body\n  }\n}\n\n/** Thrown before any provider request when a caller's argument breaks the\n *  capability's declared contract: a value that fails its `pattern`, or one the\n *  provider would refuse with a misleading answer (a commit sha where a branch\n *  name belongs reads back as \"Branch not found\"). `field` names the argument,\n *  and the message says what to pass instead. `status` is 400 so a platform\n *  classifier answers it as a settled refusal: the same arguments fail again. */\nexport class InvalidCapabilityArgument extends Error {\n  override readonly name = 'InvalidCapabilityArgument'\n  readonly status = 400\n  readonly reason = 'invalid_argument'\n  constructor(\n    message: string,\n    public readonly field: string,\n  ) {\n    super(message)\n  }\n}\n\nexport interface ConnectorManifestValidationIssue {\n  path: string\n  message: string\n}\n\nexport interface ConnectorManifestValidationResult {\n  ok: boolean\n  issues: ConnectorManifestValidationIssue[]\n}\n\n/** Validate the static connector manifest before a provider registers it.\n *  This catches the expensive mistakes early: duplicate capability names,\n *  mutation capabilities without CAS, authoritative fire-and-forget writes,\n *  and invalid rate-limit specs. */\nexport function validateConnectorManifest(manifest: ConnectorManifest): ConnectorManifestValidationResult {\n  const issues: ConnectorManifestValidationIssue[] = []\n  if (!manifest.kind.trim()) issues.push({ path: 'kind', message: 'kind is required' })\n  if (!manifest.displayName.trim()) issues.push({ path: 'displayName', message: 'displayName is required' })\n  const consistencyModels = new Set<ConsistencyModel>(['authoritative', 'cache', 'advisory'])\n  if (!consistencyModels.has(manifest.defaultConsistencyModel)) {\n    issues.push({ path: 'defaultConsistencyModel', message: 'unsupported consistency model' })\n  }\n  validateAuthSpec(manifest.auth, issues)\n  const seen = new Set<string>()\n  for (const [index, capability] of manifest.capabilities.entries()) {\n    const path = `capabilities[${index}]`\n    if (!capability.name.trim()) issues.push({ path: `${path}.name`, message: 'capability name is required' })\n    if (seen.has(capability.name)) issues.push({ path: `${path}.name`, message: `duplicate capability name: ${capability.name}` })\n    seen.add(capability.name)\n    if (capability.consistencyModel !== undefined && !consistencyModels.has(capability.consistencyModel)) {\n      issues.push({ path: `${path}.consistencyModel`, message: 'unsupported consistency model' })\n    }\n    if (capability.class === 'mutation') {\n      if (!capability.cas) issues.push({ path: `${path}.cas`, message: 'mutation capability must declare a CAS strategy' })\n      if ((capability.consistencyModel ?? manifest.defaultConsistencyModel) === 'authoritative' && capability.cas === 'none') {\n        issues.push({ path: `${path}.cas`, message: 'authoritative mutations cannot use cas=\"none\"' })\n      }\n    }\n  }\n  if (manifest.rateLimit) {\n    if (!Number.isFinite(manifest.rateLimit.requests) || manifest.rateLimit.requests <= 0) {\n      issues.push({ path: 'rateLimit.requests', message: 'rateLimit.requests must be positive' })\n    }\n    if (!Number.isFinite(manifest.rateLimit.windowMs) || manifest.rateLimit.windowMs <= 0) {\n      issues.push({ path: 'rateLimit.windowMs', message: 'rateLimit.windowMs must be positive' })\n    }\n  }\n  return { ok: issues.length === 0, issues }\n}\n\nfunction validateAuthSpec(auth: AuthSpec, issues: ConnectorManifestValidationIssue[]): void {\n  if (auth.kind === 'oauth2') {\n    validateOAuth2AuthSpec(auth, issues, 'auth')\n    return\n  }\n  if (auth.kind !== 'one_of') return\n  if (auth.options.length < 2) {\n    issues.push({ path: 'auth.options', message: 'one_of auth must declare at least two options' })\n  }\n  const optionKinds = new Set(auth.options.map((option) => option.kind))\n  if (!optionKinds.has(auth.preferred)) {\n    issues.push({ path: 'auth.preferred', message: 'one_of preferred auth must match an option kind' })\n  }\n  for (const [index, option] of auth.options.entries()) {\n    if (option.kind === 'oauth2') {\n      validateOAuth2AuthSpec(option, issues, `auth.options[${index}]`)\n    }\n  }\n}\n\nfunction validateOAuth2AuthSpec(\n  auth: OAuth2AuthSpec,\n  issues: ConnectorManifestValidationIssue[],\n  path: string,\n): void {\n  if ((auth.grantType ?? 'authorization_code') === 'authorization_code' && !auth.authorizationUrl?.trim()) {\n    issues.push({ path: `${path}.authorizationUrl`, message: 'authorization_code grant requires authorizationUrl' })\n  }\n  if (\n    auth.pkce !== undefined &&\n    auth.pkce !== 'required' &&\n    auth.pkce !== 'supported' &&\n    auth.pkce !== 'unsupported'\n  ) {\n    issues.push({\n      path: `${path}.pkce`,\n      message: 'pkce must be required, supported, or unsupported',\n    })\n  }\n  for (const [key, spec] of Object.entries(auth.urlTemplateMetadata ?? {})) {\n    if (spec.kind !== 'base-url' && spec.kind !== 'path-segment') {\n      issues.push({\n        path: `${path}.urlTemplateMetadata.${key}.kind`,\n        message: 'OAuth URL metadata kind must be base-url or path-segment',\n      })\n      continue\n    }\n    const placeholder = `{${key}}`\n    if (!auth.authorizationUrl?.includes(placeholder) && !auth.tokenUrl.includes(placeholder)) {\n      issues.push({\n        path: `${path}.urlTemplateMetadata.${key}`,\n        message: `OAuth URL metadata is unused; add ${placeholder} to an OAuth endpoint`,\n      })\n    }\n    if (spec.kind === 'base-url') {\n      if (\n        !spec.requirePublicHttps &&\n        !spec.allowedBaseUrls?.length &&\n        !spec.allowedBaseUrlSuffixes?.length\n      ) {\n        issues.push({\n          path: `${path}.urlTemplateMetadata.${key}`,\n          message: 'OAuth base URL metadata requires an allowlist or public HTTPS policy',\n        })\n      }\n      for (const suffix of spec.allowedBaseUrlSuffixes ?? []) {\n        if (!/^\\.[a-z0-9.-]+$/i.test(suffix)) {\n          issues.push({\n            path: `${path}.urlTemplateMetadata.${key}.allowedBaseUrlSuffixes`,\n            message: 'OAuth base URL hostname suffixes must start with a dot',\n          })\n        }\n      }\n    } else {\n      for (const endpoint of [auth.authorizationUrl, auth.tokenUrl]) {\n        if (\n          endpoint?.includes(placeholder) &&\n          !isOAuthPathSegmentPlaceholder(endpoint, placeholder)\n        ) {\n          issues.push({\n            path: `${path}.urlTemplateMetadata.${key}`,\n            message: `OAuth path metadata ${placeholder} must occupy a complete URL path segment`,\n          })\n        }\n      }\n    }\n  }\n  if (\n    auth.tokenClientAuthMethod !== undefined &&\n    auth.tokenClientAuthMethod !== 'none' &&\n    auth.tokenClientAuthMethod !== 'client_secret_post' &&\n    auth.tokenClientAuthMethod !== 'client_secret_basic'\n  ) {\n    issues.push({\n      path: `${path}.tokenClientAuthMethod`,\n      message: 'tokenClientAuthMethod must be none, client_secret_post, or client_secret_basic',\n    })\n  }\n  if (\n    (auth.tokenClientAuthMethod ?? 'client_secret_post') !== 'none' &&\n    !auth.clientSecretEnv?.trim()\n  ) {\n    issues.push({\n      path: `${path}.clientSecretEnv`,\n      message: 'confidential OAuth clients require clientSecretEnv',\n    })\n  }\n  for (const header of Object.keys(auth.tokenRequestHeaders ?? {})) {\n    if (header.toLowerCase() === 'authorization' || header.toLowerCase() === 'content-type') {\n      issues.push({\n        path: `${path}.tokenRequestHeaders.${header}`,\n        message: 'tokenRequestHeaders cannot override Authorization or Content-Type',\n      })\n    }\n  }\n}\n\nfunction isOAuthPathSegmentPlaceholder(template: string, placeholder: string): boolean {\n  const schemeIndex = template.indexOf('://')\n  const rootEnd = schemeIndex >= 0\n    ? schemeIndex + 3\n    : template.startsWith('{')\n      ? template.indexOf('}') + 1\n      : 0\n  const pathStart = template.indexOf('/', rootEnd)\n  const queryStart = template.search(/[?#]/)\n  let cursor = 0\n  while (true) {\n    const index = template.indexOf(placeholder, cursor)\n    if (index < 0) return true\n    const end = index + placeholder.length\n    if (\n      pathStart < 0 ||\n      index < pathStart ||\n      (queryStart >= 0 && index >= queryStart) ||\n      template[index - 1] !== '/' ||\n      (end < template.length && template[end] !== '/' && template[end] !== '?' && template[end] !== '#')\n    ) {\n      return false\n    }\n    cursor = end\n  }\n}\n\nexport function assertValidConnectorManifest(manifest: ConnectorManifest): void {\n  const result = validateConnectorManifest(manifest)\n  if (!result.ok) {\n    throw new Error(`Invalid connector manifest ${manifest.kind || '<unknown>'}: ${result.issues.map((issue) => `${issue.path}: ${issue.message}`).join('; ')}`)\n  }\n}\n"],"mappings":"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"}

package/dist/webhooks/index.d.ts

@@ -111,5 +111,10 @@ export declare function createWhatsappWebhookProvider(options: {
   phoneNumberId: string;
 }): WebhookProvider;
 //#endregion
+//#region src/webhooks/cloudbeds.d.ts
+/** Header name to pass as `authHeaderName` to `webhooks.subscribe`. */
+export declare const CLOUDBEDS_WEBHOOK_AUTH_HEADER = "x-tangle-webhook-token";
+export declare const cloudbedsWebhookProvider: WebhookProvider;
+//#endregion
 export { FileSystemWebhookIdempotencyStore, InMemoryWebhookIdempotencyStore, type InboundEmailPayload, SignatureVerification, TriggerEventCatalog, TriggerEventDescriptor, WebhookEnvelope, WebhookHeaders, WebhookIdempotencyStore, WebhookProvider, WebhookRouter, WebhookRouterOptions, WebhookRouterRequest, WebhookRouterResponse };
 //# sourceMappingURL=index.d.ts.map

package/dist/webhooks/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/webhooks/providers.ts","../../src/webhooks/twilio.ts","../../src/webhooks/messaging.ts","../../src/webhooks/whatsapp.ts"],"mappings":";;;;qBA2Ba,uBAAuB;;;;;;;;;;;;wBAyDpB,uBAAuB;EAAoB;;qBAO9C,sBAAsB;qBAgEtB,sBAAsB;qBAwDtB,yBAAyB;;;;;;qBA+CzB,sBAAsB;;;;;;;qBAyCtB,sBAAsB;;;;qBAwCtB,uBAAuB;;;;;qBAoEvB,yBAAyB;;;;;;qBAuCzB,0BAA0B;;;;;;;;;;qBAgF1B,qBAAqB;;;;wBAgGlB,2BAA2B;EACzC;EACA;EACA;EACA;;;EAGA,QAAQ;IACN;;;;wBClnBY,4BAA4B;EAC1C;EACA;EACA;EACA;IACE;;wBA+BY,+BAA+B;EAC7C;EACA;EACA;IACE;;;;wBCzBY,oBAAoB,iBAAiB,SAAS,gBAAgB,gBAAgB;;wBAyB9E,kBAAkB,iBAAiB,SAAS,gBAAgB,gBAAgB;;wBAK5E,oBAAoB,iBAAiB,SAAS,gBAAgB,gBAAgB;qBAoBjF,uBAAuB;qBAUvB,qBAAqB;qBAarB,2BAA2B;qBAc3B,6BAA6B;qBAY7B,uBAAuB;;qBAoBvB,yBAAyB;;;YCvI1B;;;wBAMI,8BAA8B;EAC5C,YAAY;EACZ;EACA;IACE"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/webhooks/providers.ts","../../src/webhooks/twilio.ts","../../src/webhooks/messaging.ts","../../src/webhooks/whatsapp.ts","../../src/webhooks/cloudbeds.ts"],"mappings":";;;;qBA2Ba,uBAAuB;;;;;;;;;;;;wBAyDpB,uBAAuB;EAAoB;;qBAO9C,sBAAsB;qBAgEtB,sBAAsB;qBAwDtB,yBAAyB;;;;;;qBA+CzB,sBAAsB;;;;;;;qBAyCtB,sBAAsB;;;;qBAwCtB,uBAAuB;;;;;qBAoEvB,yBAAyB;;;;;;qBAuCzB,0BAA0B;;;;;;;;;;qBAgF1B,qBAAqB;;;;wBAgGlB,2BAA2B;EACzC;EACA;EACA;EACA;;;EAGA,QAAQ;IACN;;;;wBClnBY,4BAA4B;EAC1C;EACA;EACA;EACA;IACE;;wBA+BY,+BAA+B;EAC7C;EACA;EACA;IACE;;;;wBCzBY,oBAAoB,iBAAiB,SAAS,gBAAgB,gBAAgB;;wBAyB9E,kBAAkB,iBAAiB,SAAS,gBAAgB,gBAAgB;;wBAK5E,oBAAoB,iBAAiB,SAAS,gBAAgB,gBAAgB;qBAoBjF,uBAAuB;qBAUvB,qBAAqB;qBAarB,2BAA2B;qBAc3B,6BAA6B;qBAY7B,uBAAuB;;qBAoBvB,yBAAyB;;;YCvI1B;;;wBAMI,8BAA8B;EAC5C,YAAY;EACZ;EACA;IACE;;;;qBCQS;qBAoBA,0BAA0B"}

package/dist/webhooks/index.js

@@ -1,5 +1,5 @@
 import { FileSystemAtomicIdempotencyStore, InMemoryAtomicIdempotencyStore, resolveAtomicIdempotencyStore } from "../idempotency.js";
-import { a as verifyHmacSignature, i as verifyEmailSignature, n as firstHeader, o as verifySlackSignature, s as verifyStripeSignature } from "../webhooks-FsjqRN_0.js";
+import { c as verifySlackSignature, i as firstHeader, l as verifyStripeSignature, o as verifyEmailSignature, s as verifyHmacSignature, t as CLOUDBEDS_WEBHOOK_EVENTS } from "../cloudbeds-BL5EF3xl.js";
 import { authenticateTwilioForm } from "../twilio/index.js";
 import { createHash, createHmac, timingSafeEqual } from "node:crypto";
 //#region src/webhooks/router.ts
@@ -1199,6 +1199,96 @@ function createWhatsappWebhookProvider(options) {
 	};
 }
 //#endregion
-export { FileSystemWebhookIdempotencyStore, InMemoryWebhookIdempotencyStore, WebhookRouter, clayWebhookProvider, clerkWebhookProvider, contiguityWebhookProvider, createTwilioSmsWebhookProvider, createTwilioWebhookProvider, createWhatsappWebhookProvider, docusealWebhookProvider, emailWebhookProvider, gdriveWebhookProvider, genericHmacWebhookProvider, gmailWebhookProvider, hellosignWebhookProvider, inkboxWebhookProvider, linqWebhookProvider, linqWhatsappWebhookProvider, resendWebhookProvider, sendblueWebhookProvider, slackHandshakeResponse, slackWebhookProvider, stripeWebhookProvider, telegramWebhookProvider, verifyInkboxWebhook, verifyLinqWebhook, verifyResendWebhook };
+//#region src/webhooks/cloudbeds.ts
+/**
+* Cloudbeds PMS webhook provider.
+*
+* Cloudbeds does not sign webhook bodies. `postWebhook` accepts an
+* `authHeaderName`/`authHeaderValue` pair, sends that header on every delivery,
+* never returns the value from `getWebhooks`, and rotates it on re-post
+* (pms-v1.3 PostWebhookRequest). Subscribe with `authHeaderName` set to
+* `CLOUDBEDS_WEBHOOK_AUTH_HEADER` and a per-connection secret as the value; the
+* verifier compares that header with the secret in constant time.
+*
+* The header proves the delivery came from a subscription holding the secret,
+* but it does not bind the body. Every envelope is a hint: consumers re-read the
+* reservation through `reservations.get` before acting on it.
+*/
+/** Header name to pass as `authHeaderName` to `webhooks.subscribe`. */
+const CLOUDBEDS_WEBHOOK_AUTH_HEADER = "x-tangle-webhook-token";
+const EVENTS = new Set(CLOUDBEDS_WEBHOOK_EVENTS.map(({ object, action }) => `${object}/${action}`));
+const NUMERIC_ID = /^[1-9]\d{0,19}$/;
+const RESERVATION_ID = /^[A-Za-z0-9_-]{1,64}$/;
+function idText(value, pattern) {
+	const text = typeof value === "number" && Number.isSafeInteger(value) ? String(value) : value;
+	return typeof text === "string" && pattern.test(text) ? text : null;
+}
+function headersOf(headers) {
+	const out = {};
+	for (const [key, value] of Object.entries(headers)) {
+		if (value === void 0 || key.toLowerCase() === "x-tangle-webhook-token") continue;
+		out[key.toLowerCase()] = Array.isArray(value) ? value.join(", ") : value;
+	}
+	return out;
+}
+const cloudbedsWebhookProvider = {
+	id: "cloudbeds",
+	verifySignature({ headers, secret }) {
+		const token = firstHeader(headers, CLOUDBEDS_WEBHOOK_AUTH_HEADER);
+		if (!token) return {
+			valid: false,
+			reason: "missing_cloudbeds_webhook_token"
+		};
+		if (!secret) return {
+			valid: false,
+			reason: "missing_secret"
+		};
+		const actual = Buffer.from(token, "utf-8");
+		const expected = Buffer.from(secret, "utf-8");
+		if (actual.length !== expected.length) return {
+			valid: false,
+			reason: "invalid_webhook_token"
+		};
+		return timingSafeEqual(actual, expected) ? { valid: true } : {
+			valid: false,
+			reason: "invalid_webhook_token"
+		};
+	},
+	parse({ rawBody, headers, now }) {
+		let body;
+		try {
+			body = JSON.parse(rawBody);
+		} catch {
+			throw new Error("cloudbeds webhook body is not JSON");
+		}
+		if (!body || typeof body !== "object" || Array.isArray(body)) throw new Error("cloudbeds webhook body is not an object");
+		const evt = body;
+		if (typeof evt.event !== "string" || !EVENTS.has(evt.event)) return [];
+		const propertyId = idText(evt.propertyID, NUMERIC_ID) ?? idText(evt.propertyID_str, NUMERIC_ID) ?? idText(evt.propertyId, NUMERIC_ID) ?? idText(evt.propertyId_str, NUMERIC_ID);
+		const reservationId = idText(evt.reservationID, RESERVATION_ID) ?? idText(evt.reservationId, RESERVATION_ID);
+		if (!propertyId || !reservationId) throw new Error("cloudbeds webhook is missing propertyId or reservationId");
+		const timestamp = typeof evt.timestamp === "number" || typeof evt.timestamp === "string" ? String(evt.timestamp) : "";
+		const [object, action] = evt.event.split("/");
+		return [{
+			provider: "cloudbeds",
+			eventType: `cloudbeds.${object}.${action}`,
+			providerEventId: createHash("sha256").update(`${evt.event}|${propertyId}|${reservationId}|${timestamp}`).digest("hex"),
+			receivedAt: now ?? Date.now(),
+			payload: {
+				...evt,
+				propertyId,
+				reservationId
+			},
+			headers: headersOf(headers)
+		}];
+	},
+	eventCatalog: {
+		namespace: "cloudbeds.",
+		closed: true,
+		events: CLOUDBEDS_WEBHOOK_EVENTS.map(({ object, action }) => ({ id: `cloudbeds.${object}.${action}` }))
+	}
+};
+//#endregion
+export { CLOUDBEDS_WEBHOOK_AUTH_HEADER, FileSystemWebhookIdempotencyStore, InMemoryWebhookIdempotencyStore, WebhookRouter, clayWebhookProvider, clerkWebhookProvider, cloudbedsWebhookProvider, contiguityWebhookProvider, createTwilioSmsWebhookProvider, createTwilioWebhookProvider, createWhatsappWebhookProvider, docusealWebhookProvider, emailWebhookProvider, gdriveWebhookProvider, genericHmacWebhookProvider, gmailWebhookProvider, hellosignWebhookProvider, inkboxWebhookProvider, linqWebhookProvider, linqWhatsappWebhookProvider, resendWebhookProvider, sendblueWebhookProvider, slackHandshakeResponse, slackWebhookProvider, stripeWebhookProvider, telegramWebhookProvider, verifyInkboxWebhook, verifyLinqWebhook, verifyResendWebhook };
 
 //# sourceMappingURL=index.js.map