@forklaunch/core 2.1.0 → 3.0.0

package/lib/http/index.js

@@ -38,15 +38,41 @@ __export(http_exports, {
   ATTR_HTTP_ROUTE: () => import_semantic_conventions.ATTR_HTTP_ROUTE,
   ATTR_SERVICE_NAME: () => import_semantic_conventions.ATTR_SERVICE_NAME,
   AuditLogger: () => AuditLogger,
+  EMAIL_LIMITS: () => EMAIL_LIMITS,
+  EmailRequestError: () => EmailRequestError,
   ForklaunchExpressLikeApplication: () => ForklaunchExpressLikeApplication,
   ForklaunchExpressLikeRouter: () => ForklaunchExpressLikeRouter,
   HTTPStatuses: () => HTTPStatuses,
+  INSTANCE_GATEWAY_MOUNT: () => INSTANCE_GATEWAY_MOUNT,
+  InstanceGatewayRequestError: () => InstanceGatewayRequestError,
+  ModelGatewayRequestError: () => ModelGatewayRequestError,
   OPENAPI_DEFAULT_VERSION: () => OPENAPI_DEFAULT_VERSION,
   OpenTelemetryCollector: () => OpenTelemetryCollector,
+  PLATFORM_EVENTS_PATH: () => PLATFORM_EVENTS_PATH,
+  PLATFORM_EVENT_KEY_ID: () => PLATFORM_EVENT_KEY_ID,
+  PaymentsRequestError: () => PaymentsRequestError,
   PinoLogger: () => PinoLogger,
+  PlatformEventVerificationError: () => PlatformEventVerificationError,
   RateLimiter: () => RateLimiter,
+  SMS_MAX_SEGMENTS: () => SMS_MAX_SEGMENTS,
+  STRIPE_GATEWAY_ROUTE: () => STRIPE_GATEWAY_ROUTE,
+  SmsClient: () => SmsClient,
+  SmsRequestError: () => SmsRequestError,
+  SmsValidationError: () => SmsValidationError,
+  VOICE_ATTRIBUTE_LIMITS: () => VOICE_ATTRIBUTE_LIMITS,
+  VoiceClient: () => VoiceClient,
+  VoiceRequestError: () => VoiceRequestError,
+  WhatsAppRequestError: () => WhatsAppRequestError,
   createContext: () => createContext,
+  createEmailClient: () => createEmailClient,
   createHmacToken: () => createHmacToken,
+  createInstanceGatewayTransport: () => createInstanceGatewayTransport,
+  createModelGatewayClient: () => createModelGatewayClient,
+  createPaymentsClient: () => createPaymentsClient,
+  createSmsClient: () => createSmsClient,
+  createStripeClient: () => createStripeClient,
+  createVoiceClient: () => createVoiceClient,
+  createWhatsAppClient: () => createWhatsAppClient,
   delete_: () => delete_,
   discriminateAuthMethod: () => discriminateAuthMethod,
   discriminateBody: () => discriminateBody,
@@ -66,10 +92,14 @@ __export(http_exports, {
   httpRequestsInFlightCounter: () => httpRequestsInFlightCounter,
   httpRequestsTotalCounter: () => httpRequestsTotalCounter,
   httpServerDurationHistogram: () => httpServerDurationHistogram,
+  instanceGatewaySettings: () => instanceGatewaySettings,
   isClientError: () => isClientError,
+  isE164: () => isE164,
+  isEmailAddress: () => isEmailAddress,
   isForklaunchRequest: () => isForklaunchRequest,
   isForklaunchRouter: () => isForklaunchRouter,
   isInformational: () => isInformational,
+  isManagedInstance: () => isManagedInstance,
   isPortBound: () => isPortBound,
   isRedirection: () => isRedirection,
   isServerError: () => isServerError,
@@ -85,9 +115,16 @@ __export(http_exports, {
   put: () => put,
   recordMetric: () => recordMetric,
   resetProcessHandlersForTesting: () => resetProcessHandlersForTesting,
+  signPlatformEvent: () => signPlatformEvent,
+  smsSegments: () => smsSegments,
+  stripeGatewayFetch: () => stripeGatewayFetch,
   trace: () => trace3,
   typedAuthHandler: () => typedAuthHandler,
-  typedHandler: () => typedHandler
+  typedHandler: () => typedHandler,
+  validateEmailSendRequest: () => validateEmailSendRequest,
+  validateSmsSend: () => validateSmsSend,
+  verifyPlatformEvent: () => verifyPlatformEvent,
+  voiceRequestProblem: () => voiceRequestProblem
 });
 module.exports = __toCommonJS(http_exports);
 
@@ -2474,6 +2511,778 @@ function generateHmacAuthHeaders({
   };
 }
 
+// src/http/instanceGateway.ts
+var import_crypto4 = require("crypto");
+var INSTANCE_GATEWAY_MOUNT = "/instance-gateway";
+var PLATFORM_EVENT_KEY_ID = "platform";
+var PLATFORM_EVENTS_PATH = "/platform-events";
+var MAX_SKEW_MS = 5 * 60 * 1e3;
+var InstanceGatewayRequestError = class extends Error {
+  constructor(status, message, retryAfterSeconds) {
+    super(message);
+    this.status = status;
+    this.retryAfterSeconds = retryAfterSeconds;
+  }
+  status;
+  retryAfterSeconds;
+  name = "InstanceGatewayRequestError";
+};
+function instanceGatewaySettings(options2 = {}, feature = "The instance gateway") {
+  const gatewayUrl = options2.gatewayUrl ?? process.env.PLATFORM_GATEWAY_URL;
+  const instanceId = options2.instanceId ?? process.env.INSTANCE_ID;
+  const hmacKey = options2.hmacKey ?? process.env.INSTANCE_HMAC_KEY;
+  if (!gatewayUrl || !instanceId || !hmacKey) {
+    throw new Error(
+      `${feature} is only available to instances hosted in managed mode: PLATFORM_GATEWAY_URL, INSTANCE_ID and INSTANCE_HMAC_KEY must be set`
+    );
+  }
+  return { gatewayUrl, instanceId, hmacKey };
+}
+function isManagedInstance(env = process.env) {
+  return Boolean(
+    env.PLATFORM_GATEWAY_URL && env.INSTANCE_ID && env.INSTANCE_HMAC_KEY
+  );
+}
+function trimTrailingSlashes(value) {
+  let end = value.length;
+  while (end > 0 && value[end - 1] === "/") end -= 1;
+  return value.slice(0, end);
+}
+function createInstanceGatewayTransport(options2 = {}, feature) {
+  const { gatewayUrl, instanceId, hmacKey } = instanceGatewaySettings(
+    options2,
+    feature
+  );
+  const fetchImpl = options2.fetch ?? fetch;
+  const base = trimTrailingSlashes(gatewayUrl);
+  const request = async (method, route, body, requestOptions = {}) => {
+    const { authorization } = generateHmacAuthHeaders({
+      secretKey: hmacKey,
+      method,
+      path: route,
+      body,
+      keyId: instanceId
+    });
+    const response = await fetchImpl(`${base}${INSTANCE_GATEWAY_MOUNT}${route}`, {
+      method,
+      headers: {
+        ...requestOptions.headers,
+        authorization,
+        ...body ? { "content-type": "application/json" } : {}
+      },
+      body: body ? JSON.stringify(body) : void 0,
+      signal: requestOptions.signal
+    });
+    if (!response.ok) {
+      const message = (await response.text().catch(() => "")).trim();
+      const retryAfter = Number(response.headers.get("retry-after"));
+      throw new InstanceGatewayRequestError(
+        response.status,
+        message || `Instance gateway answered ${response.status}`,
+        Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter : void 0
+      );
+    }
+    return response;
+  };
+  return {
+    instanceId,
+    request,
+    async json(method, route, body, requestOptions) {
+      return await (await request(method, route, body, requestOptions)).json();
+    }
+  };
+}
+var PlatformEventVerificationError = class extends Error {
+  name = "PlatformEventVerificationError";
+};
+var seenEventNonces = /* @__PURE__ */ new Map();
+function verifyPlatformEvent(request, options2 = {}) {
+  const hmacKey = options2.hmacKey ?? process.env.INSTANCE_HMAC_KEY;
+  if (!hmacKey) {
+    throw new PlatformEventVerificationError(
+      "INSTANCE_HMAC_KEY is not set: this service is not a managed instance"
+    );
+  }
+  const header = request.headers.authorization ?? request.headers.Authorization;
+  const value = Array.isArray(header) ? header[0] : header;
+  const match = /^HMAC keyId=(\S+) ts=(\S+) nonce=(\S+) signature=(\S+)$/.exec(
+    value ?? ""
+  );
+  if (!match) {
+    throw new PlatformEventVerificationError(
+      "Missing or malformed HMAC authorization"
+    );
+  }
+  const [, keyId, ts, nonce, signature] = match;
+  if (keyId !== PLATFORM_EVENT_KEY_ID) {
+    throw new PlatformEventVerificationError("Not signed by the platform");
+  }
+  const timestamp = new Date(ts);
+  const now = (options2.now ?? Date.now)();
+  if (Number.isNaN(timestamp.getTime()) || Math.abs(now - timestamp.getTime()) > MAX_SKEW_MS) {
+    throw new PlatformEventVerificationError("Stale or invalid timestamp");
+  }
+  const expected = Buffer.from(
+    createHmacToken({
+      secretKey: hmacKey,
+      method: request.method.toUpperCase(),
+      path: request.path,
+      body: request.body,
+      timestamp,
+      nonce
+    })
+  );
+  const received = Buffer.from(signature);
+  if (expected.length !== received.length || !(0, import_crypto4.timingSafeEqual)(expected, received)) {
+    throw new PlatformEventVerificationError("Invalid signature");
+  }
+  for (const [seen, at] of seenEventNonces) {
+    if (now - at > MAX_SKEW_MS) seenEventNonces.delete(seen);
+  }
+  if (seenEventNonces.has(nonce)) {
+    throw new PlatformEventVerificationError("Replayed delivery");
+  }
+  seenEventNonces.set(nonce, now);
+  const parsed = typeof request.body === "string" || Buffer.isBuffer(request.body) ? JSON.parse(request.body.toString()) : request.body;
+  const event = parsed;
+  if (!event || typeof event.id !== "string" || typeof event.type !== "string" || typeof event.feature !== "string") {
+    throw new PlatformEventVerificationError("Body is not a platform event");
+  }
+  return event;
+}
+function signPlatformEvent(params) {
+  return generateHmacAuthHeaders({
+    secretKey: params.hmacKey,
+    method: "POST",
+    path: params.path,
+    body: params.body,
+    keyId: PLATFORM_EVENT_KEY_ID
+  });
+}
+
+// src/http/modelGatewayClient.ts
+var ModelGatewayRequestError = class extends InstanceGatewayRequestError {
+  name = "ModelGatewayRequestError";
+};
+function createModelGatewayClient(options2 = {}) {
+  const transport = createInstanceGatewayTransport(options2, "The model gateway");
+  async function send(method, route, body, signal) {
+    try {
+      return await transport.request(method, route, body, { signal });
+    } catch (error) {
+      if (error instanceof InstanceGatewayRequestError) {
+        throw new ModelGatewayRequestError(
+          error.status,
+          error.message,
+          error.retryAfterSeconds
+        );
+      }
+      throw error;
+    }
+  }
+  return {
+    async models() {
+      return await (await send("GET", "/models")).json();
+    },
+    chat: {
+      completions: {
+        async create(request) {
+          const response = await send(
+            "POST",
+            "/models/chat/completions",
+            request
+          );
+          return await response.json();
+        },
+        async *stream(request, streamOptions = {}) {
+          const response = await send(
+            "POST",
+            "/models/chat/completions/stream",
+            request,
+            streamOptions.signal
+          );
+          if (!response.body) return;
+          for await (const data of sseData(response.body)) {
+            if (data === "[DONE]") return;
+            try {
+              yield JSON.parse(data);
+            } catch {
+            }
+          }
+        }
+      }
+    }
+  };
+}
+async function* sseData(stream) {
+  const decoder = new TextDecoder();
+  let buffer = "";
+  const reader = stream.getReader();
+  try {
+    for (; ; ) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      let boundary;
+      while ((boundary = buffer.search(/\r?\n\r?\n/)) !== -1) {
+        const event = buffer.slice(0, boundary);
+        buffer = buffer.slice(boundary).replace(/^\r?\n\r?\n/, "");
+        const data = event.split(/\r?\n/).filter((line) => line.startsWith("data:")).map((line) => line.slice(5).trimStart()).join("\n");
+        if (data) yield data;
+      }
+    }
+    const tail = buffer.trim();
+    if (tail.startsWith("data:")) yield tail.slice(5).trimStart();
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+// src/http/emailClient.ts
+var EmailRequestError = class extends InstanceGatewayRequestError {
+  name = "EmailRequestError";
+};
+var EMAIL_LIMITS = {
+  maxRecipients: 50,
+  maxAddressLength: 254,
+  maxSubjectLength: 998,
+  /** text + html, UTF-8 bytes. */
+  maxBodyBytes: 512 * 1024,
+  maxTags: 10
+};
+var ADDRESS = /^[^\s@<>()[\]\\,;:"]+@[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?)+$/;
+var TAG_PART = /^[A-Za-z0-9_-]{1,256}$/;
+function isEmailAddress(address) {
+  return typeof address === "string" && address.length <= EMAIL_LIMITS.maxAddressLength && ADDRESS.test(address);
+}
+function refuse(message) {
+  throw new EmailRequestError(400, message);
+}
+function addresses(value, field) {
+  if (value === void 0) return void 0;
+  const list = Array.isArray(value) ? value : [value];
+  if (list.length === 0) refuse(`${field} must name at least one address`);
+  if (list.length > EMAIL_LIMITS.maxRecipients) {
+    refuse(
+      `${field} has ${list.length} addresses; the limit is ${EMAIL_LIMITS.maxRecipients}`
+    );
+  }
+  for (const address of list) {
+    if (!isEmailAddress(address)) {
+      refuse(
+        `${field}: '${String(address).slice(0, 80)}' is not an email address`
+      );
+    }
+  }
+  return list;
+}
+function validateEmailSendRequest(request) {
+  const to = addresses(request.to, "to") ?? refuse("to is required");
+  const replyTo = addresses(request.replyTo, "replyTo");
+  const subject = request.subject;
+  if (typeof subject !== "string" || subject.trim() === "") {
+    refuse("subject is required");
+  }
+  if (/[\r\n]/.test(subject)) refuse("subject must be one line");
+  if (subject.length > EMAIL_LIMITS.maxSubjectLength) {
+    refuse(
+      `subject is longer than ${EMAIL_LIMITS.maxSubjectLength} characters`
+    );
+  }
+  if (!request.text && !request.html) refuse("text or html is required");
+  const bytes = Buffer.byteLength(request.text ?? "", "utf8") + Buffer.byteLength(request.html ?? "", "utf8");
+  if (bytes > EMAIL_LIMITS.maxBodyBytes) {
+    refuse(`body is ${bytes} bytes; the limit is ${EMAIL_LIMITS.maxBodyBytes}`);
+  }
+  const tags = request.tags ?? {};
+  const names = Object.keys(tags);
+  if (names.length > EMAIL_LIMITS.maxTags) {
+    refuse(`${names.length} tags; the limit is ${EMAIL_LIMITS.maxTags}`);
+  }
+  for (const name of names) {
+    if (!TAG_PART.test(name) || !TAG_PART.test(String(tags[name]))) {
+      refuse(`tag '${name}': names and values are letters, digits, _ and -`);
+    }
+    if (name.startsWith("fl-") || name.startsWith("ses:")) {
+      refuse(`tag '${name}' is reserved`);
+    }
+  }
+  return {
+    to,
+    subject,
+    ...request.text !== void 0 ? { text: request.text } : {},
+    ...request.html !== void 0 ? { html: request.html } : {},
+    ...replyTo ? { replyTo } : {},
+    ...names.length ? { tags } : {}
+  };
+}
+function createEmailClient(options2 = {}) {
+  if (!isManagedInstance({
+    PLATFORM_GATEWAY_URL: options2.gatewayUrl ?? process.env.PLATFORM_GATEWAY_URL,
+    INSTANCE_ID: options2.instanceId ?? process.env.INSTANCE_ID,
+    INSTANCE_HMAC_KEY: options2.hmacKey ?? process.env.INSTANCE_HMAC_KEY
+  })) {
+    throw new Error(
+      "Email is sent by the ForkLaunch platform and is only available to managed instances: PLATFORM_GATEWAY_URL, INSTANCE_ID and INSTANCE_HMAC_KEY must be set. Locally, `forklaunch infra add <service> email` sets them to the gateway mock in docker-compose."
+    );
+  }
+  const transport = createInstanceGatewayTransport(options2, "Email");
+  async function call(method, route, body) {
+    try {
+      return await transport.json(method, route, body);
+    } catch (error) {
+      if (error instanceof InstanceGatewayRequestError) {
+        throw new EmailRequestError(
+          error.status,
+          error.message,
+          error.retryAfterSeconds
+        );
+      }
+      throw error;
+    }
+  }
+  return {
+    async send(request) {
+      return call(
+        "POST",
+        "/email/send",
+        validateEmailSendRequest(request)
+      );
+    },
+    async suppressed(address) {
+      if (!isEmailAddress(address)) {
+        refuse(`'${String(address).slice(0, 80)}' is not an email address`);
+      }
+      const answer = await call(
+        "GET",
+        `/email/suppressions/${encodeURIComponent(address.toLowerCase())}`
+      );
+      return answer.suppressed === true;
+    }
+  };
+}
+
+// src/http/smsClient.ts
+var SmsRequestError = class extends InstanceGatewayRequestError {
+  name = "SmsRequestError";
+};
+var SmsValidationError = class extends Error {
+  name = "SmsValidationError";
+};
+var SMS_MAX_SEGMENTS = 10;
+var E164 = /^\+[1-9]\d{6,14}$/;
+function isE164(phone) {
+  return E164.test(phone);
+}
+var GSM_BASIC = new Set(
+  `@\xA3$\xA5\xE8\xE9\xF9\xEC\xF2\xC7
+\xD8\xF8\r\xC5\xE5\u0394_\u03A6\u0393\u039B\u03A9\u03A0\u03A8\u03A3\u0398\u039E\xC6\xE6\xDF\xC9 !"#\xA4%&'()*+,-./0123456789:;<=>?\xA1ABCDEFGHIJKLMNOPQRSTUVWXYZ\xC4\xD6\xD1\xDC\xA7\xBFabcdefghijklmnopqrstuvwxyz\xE4\xF6\xF1\xFC\xE0`
+);
+var GSM_EXTENDED = new Set("^{}\\[~]|\u20AC\f");
+function smsSegments(body) {
+  let septets = 0;
+  let gsm = true;
+  for (const ch of body) {
+    if (GSM_BASIC.has(ch)) septets += 1;
+    else if (GSM_EXTENDED.has(ch)) septets += 2;
+    else {
+      gsm = false;
+      break;
+    }
+  }
+  if (gsm) {
+    return {
+      encoding: "GSM-7",
+      units: septets,
+      segments: septets <= 160 ? 1 : Math.ceil(septets / 153)
+    };
+  }
+  const units = body.length;
+  return {
+    encoding: "UCS-2",
+    units,
+    segments: units <= 70 ? 1 : Math.ceil(units / 67)
+  };
+}
+function validateSmsSend(request) {
+  if (typeof request.to !== "string" || !isE164(request.to)) {
+    throw new SmsValidationError(
+      `'to' must be an E.164 number like +14155550123 (got ${JSON.stringify(request.to)})`
+    );
+  }
+  if (typeof request.body !== "string" || !request.body.trim()) {
+    throw new SmsValidationError("'body' must be non-empty text");
+  }
+  const { segments, encoding } = smsSegments(request.body);
+  if (segments > SMS_MAX_SEGMENTS) {
+    throw new SmsValidationError(
+      `'body' is ${segments} ${encoding} segments; the limit is ${SMS_MAX_SEGMENTS}. Send a link instead of long text.`
+    );
+  }
+  if (request.purpose !== void 0 && request.purpose !== "transactional" && request.purpose !== "promotional") {
+    throw new SmsValidationError(
+      "'purpose' must be 'transactional' or 'promotional'"
+    );
+  }
+}
+var NOT_MANAGED = "SMS is platform-held: this service must run as a managed instance (PLATFORM_GATEWAY_URL, INSTANCE_ID and INSTANCE_HMAC_KEY set). Locally, run the gateway mock (npx -p @forklaunch/core forklaunch-gateway-mock) and point those variables at it; do not add a Twilio or AWS SDK.";
+var SmsClient = class {
+  transport;
+  constructor(options2 = {}) {
+    const configured = Boolean(
+      (options2.gatewayUrl ?? process.env.PLATFORM_GATEWAY_URL) && (options2.instanceId ?? process.env.INSTANCE_ID) && (options2.hmacKey ?? process.env.INSTANCE_HMAC_KEY)
+    ) || isManagedInstance();
+    if (configured) {
+      this.transport = createInstanceGatewayTransport(options2, "SMS");
+    } else if (!options2.deferRefusal) {
+      throw new Error(NOT_MANAGED);
+    }
+  }
+  /** Whether sends can reach the gateway (false: every send refuses). */
+  get managed() {
+    return this.transport !== void 0;
+  }
+  async send(request) {
+    validateSmsSend(request);
+    if (!this.transport) throw new Error(NOT_MANAGED);
+    try {
+      return await this.transport.json("POST", "/sms/send", {
+        to: request.to,
+        body: request.body,
+        purpose: request.purpose ?? "transactional"
+      });
+    } catch (error) {
+      if (error instanceof InstanceGatewayRequestError) {
+        throw new SmsRequestError(
+          error.status,
+          error.message,
+          error.retryAfterSeconds
+        );
+      }
+      throw error;
+    }
+  }
+};
+function createSmsClient(options2 = {}) {
+  return new SmsClient(options2);
+}
+
+// src/http/whatsappClient.ts
+var WhatsAppRequestError = class extends InstanceGatewayRequestError {
+  name = "WhatsAppRequestError";
+};
+var E1642 = /^\+[1-9]\d{6,14}$/;
+function requireRecipient(to) {
+  if (typeof to !== "string" || !E1642.test(to)) {
+    throw new WhatsAppRequestError(
+      400,
+      `'to' must be an E.164 phone number such as +14155550123 (got ${JSON.stringify(to)})`
+    );
+  }
+}
+function createConversationChannelClient(channel, label, options2) {
+  const transport = createInstanceGatewayTransport(options2, label);
+  async function call(method, route, body) {
+    try {
+      return await transport.json(method, `/${channel}${route}`, body);
+    } catch (error) {
+      if (error instanceof InstanceGatewayRequestError) {
+        throw new WhatsAppRequestError(
+          error.status,
+          error.message,
+          error.retryAfterSeconds
+        );
+      }
+      throw error;
+    }
+  }
+  return {
+    async sendTemplate(request) {
+      requireRecipient(request.to);
+      if (!request.template || !request.language) {
+        throw new WhatsAppRequestError(
+          400,
+          "template and language are required"
+        );
+      }
+      return call("POST", "/messages", {
+        to: request.to,
+        type: "template",
+        template: request.template,
+        language: request.language,
+        ...request.components ? { components: request.components } : {}
+      });
+    },
+    async sendText(request) {
+      requireRecipient(request.to);
+      if (typeof request.body !== "string" || !request.body.trim()) {
+        throw new WhatsAppRequestError(400, "body must be non-empty text");
+      }
+      return call("POST", "/messages", {
+        to: request.to,
+        type: "text",
+        body: request.body
+      });
+    },
+    async templates() {
+      const listing = await call(
+        "GET",
+        "/templates"
+      );
+      return listing.templates;
+    }
+  };
+}
+function createWhatsAppClient(options2 = {}) {
+  return createConversationChannelClient("whatsapp", "WhatsApp", options2);
+}
+
+// src/http/voiceClient.ts
+var VOICE_ATTRIBUTE_LIMITS = {
+  maxKeys: 20,
+  maxKeyLength: 64,
+  maxValueLength: 256,
+  maxTotalBytes: 4096,
+  /** Keys the platform reserves (it prefixes and adds its own under `fl_`). */
+  reservedPrefix: "fl_"
+};
+var VoiceRequestError = class extends InstanceGatewayRequestError {
+  name = "VoiceRequestError";
+};
+var E1643 = /^\+[1-9]\d{6,14}$/;
+var FLOW_NAME = /^[a-z][a-z0-9_-]{0,63}$/;
+var ATTRIBUTE_KEY = /^[A-Za-z][A-Za-z0-9_]*$/;
+function voiceRequestProblem(request) {
+  if (typeof request.to !== "string" || !E1643.test(request.to)) {
+    return "`to` must be an E.164 number such as +15551230000";
+  }
+  if (typeof request.flow !== "string" || request.flow.startsWith("arn:")) {
+    return "`flow` is a flow name from the product catalog (e.g. appointment_reminder), not a contact-flow ARN";
+  }
+  if (!FLOW_NAME.test(request.flow)) {
+    return "`flow` must be a catalog flow name: lowercase letters, digits, _ or -";
+  }
+  const attributes = request.attributes ?? {};
+  if (typeof attributes !== "object" || Array.isArray(attributes)) {
+    return "`attributes` must be an object of strings";
+  }
+  const entries = Object.entries(attributes);
+  const limits = VOICE_ATTRIBUTE_LIMITS;
+  if (entries.length > limits.maxKeys) {
+    return `at most ${limits.maxKeys} attributes`;
+  }
+  let total = 0;
+  for (const [key, value] of entries) {
+    if (!ATTRIBUTE_KEY.test(key) || key.length > limits.maxKeyLength) {
+      return `attribute key '${key}' must be letters, digits or _ (max ${limits.maxKeyLength})`;
+    }
+    if (key.toLowerCase().startsWith(limits.reservedPrefix)) {
+      return `attribute keys starting with '${limits.reservedPrefix}' are reserved for the platform`;
+    }
+    if (typeof value !== "string") {
+      return `attribute '${key}' must be a string`;
+    }
+    if (value.length > limits.maxValueLength) {
+      return `attribute '${key}' is longer than ${limits.maxValueLength} characters`;
+    }
+    total += Buffer.byteLength(key) + Buffer.byteLength(value);
+  }
+  if (total > limits.maxTotalBytes) {
+    return `attributes exceed ${limits.maxTotalBytes} bytes`;
+  }
+  return void 0;
+}
+var VoiceClient = class {
+  transport;
+  /** Throws when the process is not a managed instance (see instanceGatewaySettings). */
+  constructor(options2 = {}) {
+    this.transport = createInstanceGatewayTransport(
+      options2,
+      "Voice calls (createVoiceClient)"
+    );
+  }
+  /** Place an outbound call; resolves once the platform accepted it. */
+  async startOutboundCall(request) {
+    const problem = voiceRequestProblem(request);
+    if (problem) throw new VoiceRequestError(400, problem);
+    return this.send("POST", "/voice/calls", {
+      to: request.to,
+      flow: request.flow,
+      ...request.attributes ? { attributes: request.attributes } : {}
+    });
+  }
+  /** Hang up a call this instance placed. */
+  async endCall(callId) {
+    await this.send("DELETE", callPath(callId));
+  }
+  /** Where a call this instance placed stands. */
+  async call(callId) {
+    return this.send("GET", callPath(callId));
+  }
+  async send(method, route, body) {
+    try {
+      const response = await this.transport.request(method, route, body);
+      const text = await response.text();
+      return text ? JSON.parse(text) : void 0;
+    } catch (error) {
+      if (error instanceof InstanceGatewayRequestError) {
+        throw new VoiceRequestError(
+          error.status,
+          error.message,
+          error.retryAfterSeconds
+        );
+      }
+      throw error;
+    }
+  }
+};
+function callPath(callId) {
+  if (typeof callId !== "string" || !/^[A-Za-z0-9_-]{1,128}$/.test(callId)) {
+    throw new VoiceRequestError(400, "callId is not a call id");
+  }
+  return `/voice/calls/${callId}`;
+}
+function createVoiceClient(options2 = {}) {
+  return new VoiceClient(options2);
+}
+
+// src/http/paymentsClient.ts
+var import_node_module = require("module");
+var import_meta = {};
+var STRIPE_GATEWAY_ROUTE = "/stripe";
+var PaymentsRequestError = class extends InstanceGatewayRequestError {
+  name = "PaymentsRequestError";
+};
+function createPaymentsClient(options2 = {}) {
+  const transport = createInstanceGatewayTransport(options2, "Payments");
+  async function call(method, route, body) {
+    try {
+      return await transport.json(method, route, body);
+    } catch (error) {
+      if (error instanceof InstanceGatewayRequestError) {
+        throw new PaymentsRequestError(
+          error.status,
+          error.message,
+          error.retryAfterSeconds
+        );
+      }
+      throw error;
+    }
+  }
+  return {
+    onboardingLink({ returnUrl, refreshUrl }) {
+      for (const [name, value] of [
+        ["returnUrl", returnUrl],
+        ["refreshUrl", refreshUrl]
+      ]) {
+        if (!/^https?:\/\//.test(value ?? "")) {
+          throw new TypeError(`${name} must be an absolute http(s) URL`);
+        }
+      }
+      return call("POST", "/payments/onboarding-link", {
+        returnUrl,
+        refreshUrl
+      });
+    },
+    status() {
+      return call("GET", "/payments/status");
+    }
+  };
+}
+function loadStripe() {
+  const load = (0, import_node_module.createRequire)(
+    typeof __filename === "string" ? __filename : import_meta.url
+  );
+  try {
+    const mod = load("stripe");
+    return mod.default ?? mod;
+  } catch {
+    throw new Error(
+      "createStripeClient needs the 'stripe' package: add it to this service (pnpm add stripe)"
+    );
+  }
+}
+function stripeGatewayFetch(settings, fetchImpl = fetch) {
+  const base = new URL(settings.gatewayUrl);
+  const basePath = base.pathname.replace(/\/+$/, "");
+  return async (input, init = {}) => {
+    const original = new URL(
+      typeof input === "string" || input instanceof URL ? input : input.url
+    );
+    const routerPath = `${STRIPE_GATEWAY_ROUTE}${original.pathname}${original.search}`;
+    const method = (init.method ?? "GET").toUpperCase();
+    const body = typeof init.body === "string" ? init.body : void 0;
+    const { authorization } = generateHmacAuthHeaders({
+      secretKey: settings.hmacKey,
+      method,
+      path: routerPath,
+      body: body || void 0,
+      keyId: settings.instanceId
+    });
+    const headers = new Headers(init.headers);
+    headers.set("authorization", authorization);
+    const target = `${base.origin}${basePath}${INSTANCE_GATEWAY_MOUNT}${routerPath}`;
+    const response = await fetchImpl(target, { ...init, method, headers });
+    if (response.ok || (response.headers.get("content-type") ?? "").includes("json")) {
+      return response;
+    }
+    const message = (await response.text().catch(() => "")).trim() || `Instance gateway answered ${response.status}`;
+    return new Response(
+      JSON.stringify({
+        error: {
+          type: "invalid_request_error",
+          code: "forklaunch_gateway",
+          message
+        }
+      }),
+      {
+        status: response.status,
+        headers: {
+          "content-type": "application/json",
+          "stripe-should-retry": "false",
+          ...response.headers.get("retry-after") ? { "retry-after": response.headers.get("retry-after") } : {}
+        }
+      }
+    );
+  };
+}
+function createStripeClient(options2 = {}) {
+  const StripeClass = options2.Stripe ?? loadStripe();
+  const explicitGateway = Boolean(
+    options2.gatewayUrl || options2.instanceId || options2.hmacKey
+  );
+  if (!explicitGateway && !isManagedInstance()) {
+    if (!options2.apiKey) {
+      throw new Error(
+        "createStripeClient: not a managed instance (PLATFORM_GATEWAY_URL, INSTANCE_ID and INSTANCE_HMAC_KEY are unset) and no apiKey was given \u2014 pass { apiKey } for local development, or run the gateway mock (forklaunch-gateway-mock) with the managed env"
+      );
+    }
+    return new StripeClass(options2.apiKey, options2.config);
+  }
+  const settings = instanceGatewaySettings(options2, "Payments");
+  const gateway = new URL(settings.gatewayUrl);
+  const protocol = gateway.protocol === "http:" ? "http" : "https";
+  return new StripeClass(
+    // No key: the authenticator below replaces it, and the gateway holds the
+    // real one. (stripe-node accepts an authenticator in place of a key.)
+    void 0,
+    {
+      maxNetworkRetries: 2,
+      ...options2.config,
+      host: gateway.hostname,
+      port: gateway.port || (protocol === "http" ? 80 : 443),
+      protocol,
+      telemetry: false,
+      // The signed fetch sets `authorization`; nothing else may.
+      authenticator: async () => {
+      },
+      httpClient: StripeClass.createFetchHttpClient(
+        stripeGatewayFetch(settings, options2.fetch)
+      )
+    }
+  );
+}
+
 // src/http/guards/isPath.ts
 function isPath(path) {
   return path.startsWith("/");
@@ -4435,7 +5244,7 @@ function generateOpenApiSpecs(schemaValidator, serverUrls, serverDescriptions, a
 }
 
 // src/http/telemetry/auditLogger.ts
-var import_crypto4 = require("crypto");
+var import_crypto5 = require("crypto");
 var AuditLogger = class {
   _otel;
   constructor(otel) {
@@ -4468,7 +5277,7 @@ var AuditLogger = class {
     if (body === void 0 || body === null || body === "") {
       return "";
     }
-    return (0, import_crypto4.createHash)("sha256").update(body).digest("hex");
+    return (0, import_crypto5.createHash)("sha256").update(body).digest("hex");
   }
 };
 
@@ -4570,15 +5379,41 @@ var RateLimiter = class {
   ATTR_HTTP_ROUTE,
   ATTR_SERVICE_NAME,
   AuditLogger,
+  EMAIL_LIMITS,
+  EmailRequestError,
   ForklaunchExpressLikeApplication,
   ForklaunchExpressLikeRouter,
   HTTPStatuses,
+  INSTANCE_GATEWAY_MOUNT,
+  InstanceGatewayRequestError,
+  ModelGatewayRequestError,
   OPENAPI_DEFAULT_VERSION,
   OpenTelemetryCollector,
+  PLATFORM_EVENTS_PATH,
+  PLATFORM_EVENT_KEY_ID,
+  PaymentsRequestError,
   PinoLogger,
+  PlatformEventVerificationError,
   RateLimiter,
+  SMS_MAX_SEGMENTS,
+  STRIPE_GATEWAY_ROUTE,
+  SmsClient,
+  SmsRequestError,
+  SmsValidationError,
+  VOICE_ATTRIBUTE_LIMITS,
+  VoiceClient,
+  VoiceRequestError,
+  WhatsAppRequestError,
   createContext,
+  createEmailClient,
   createHmacToken,
+  createInstanceGatewayTransport,
+  createModelGatewayClient,
+  createPaymentsClient,
+  createSmsClient,
+  createStripeClient,
+  createVoiceClient,
+  createWhatsAppClient,
   delete_,
   discriminateAuthMethod,
   discriminateBody,
@@ -4598,10 +5433,14 @@ var RateLimiter = class {
   httpRequestsInFlightCounter,
   httpRequestsTotalCounter,
   httpServerDurationHistogram,
+  instanceGatewaySettings,
   isClientError,
+  isE164,
+  isEmailAddress,
   isForklaunchRequest,
   isForklaunchRouter,
   isInformational,
+  isManagedInstance,
   isPortBound,
   isRedirection,
   isServerError,
@@ -4617,8 +5456,15 @@ var RateLimiter = class {
   put,
   recordMetric,
   resetProcessHandlersForTesting,
+  signPlatformEvent,
+  smsSegments,
+  stripeGatewayFetch,
   trace,
   typedAuthHandler,
-  typedHandler
+  typedHandler,
+  validateEmailSendRequest,
+  validateSmsSend,
+  verifyPlatformEvent,
+  voiceRequestProblem
 });
 //# sourceMappingURL=index.js.map