@stripe/extensibility-sdk 0.22.4

package/tslibs/lib.egress.globals.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Global runtime functions provided by the script execution environment.
+ * These are available at runtime but need to be declared for TypeScript.
+ */
+
+/**
+ * HTTP method types supported by endpointFetch.
+ */
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+
+/**
+ * Request object for endpointFetch.
+ */
+interface EndpointFetchRequest {
+  /** The endpoint identifier (references app manifest). */
+  endpoint: string;
+  /** URL path suffix (e.g., "/v1/send_message"). */
+  path: string;
+  /** HTTP method. */
+  method: HttpMethod;
+  /** Request body (JSON string). */
+  body?: string;
+  /** HTTP headers. */
+  headers?: Record<string, string>;
+}
+
+/**
+ * Successful response object from endpointFetch (2xx only).
+ */
+interface EndpointFetchResponse {
+  /** Always true for successful responses. */
+  ok: true;
+  /** HTTP status code (200-299). */
+  status: number;
+  /** Response body (JSON string). */
+  body?: string;
+}
+
+/**
+ * Error codes set on exceptions thrown by endpointFetch.
+ *
+ * - EXT_* codes: the upstream endpoint returned a non-2xx HTTP response.
+ * - ERR_* codes: infrastructure or network failure prevented the request.
+ */
+type EndpointFetchErrorCode =
+  | 'EXT_BAD_REQUEST'
+  | 'EXT_UNAUTHORIZED'
+  | 'EXT_NOT_ALLOWED'
+  | 'EXT_NOT_FOUND'
+  | 'EXT_RATE_LIMIT'
+  | 'EXT_RUNTIME_ERROR'
+  | 'EXT_RESOURCE_UNAVAILABLE'
+  | 'EXT_TIMEOUT'
+  | 'ERR_INTERNAL'
+  | 'ERR_NETWORK'
+  | 'ERR_PROFILE';
+
+/**
+ * Error thrown by endpointFetch on non-2xx responses or infrastructure failures.
+ *
+ * For HTTP errors (EXT_* codes), `status` and `body` contain the upstream response.
+ * For infra/network errors (ERR_* codes), `status` and `body` are undefined.
+ */
+interface EndpointFetchError extends Error {
+  /** Error code for classification. */
+  code?: EndpointFetchErrorCode;
+  /** HTTP status code (present for EXT_* errors). */
+  status?: number;
+  /** Response body string (present for EXT_* errors, null if upstream returned empty). */
+  body?: string | null;
+}
+
+/**
+ * Makes an async HTTP request to an external endpoint.
+ *
+ * Only available in the Egress execution profile.
+ *
+ * - Resolves with an {@link EndpointFetchResponse} for 2xx responses.
+ * - Rejects with an {@link EndpointFetchError} for non-2xx responses, network failures,
+ *   and infrastructure failures.
+ *
+ * @param request - The request object.
+ * @returns A promise resolving to the response object (2xx only).
+ * @throws {EndpointFetchError} On non-2xx HTTP responses (EXT_* codes),
+ *                              infrastructure failures (ERR_INTERNAL),
+ *                              network failures (ERR_NETWORK),
+ *                              or profile violations (ERR_PROFILE).
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const result = await endpointFetch({
+ *     endpoint: "test_api",
+ *     path: "/v1/test",
+ *     method: "POST",
+ *     body: JSON.stringify({ key: "value" }),
+ *   });
+ *   const data = JSON.parse(result.body!);
+ *   return { success: true, ts: data.ts };
+ * } catch (e) {
+ *   const error = e as EndpointFetchError;
+ *   if (error.code === 'EXT_RATE_LIMIT') {
+ *     return { success: false, retriable: true, reason: 'rate_limited' };
+ *   }
+ *   if (error.status) {
+ *     return { success: false, status: error.status };
+ *   }
+ *   throw error; // re-throw infra errors for automatic retry
+ * }
+ * ```
+ */
+declare function endpointFetch(request: EndpointFetchRequest): Promise<EndpointFetchResponse>;

package/tslibs/lib.restricted.globals.d.ts

@@ -0,0 +1 @@
+// No runtime globals are available in the restricted execution profile.