@elaraai/east-web-std 1.0.85

package/dist/src/fetch.d.ts

@@ -0,0 +1,383 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+import { StringType, IntegerType, BooleanType, DictType, OptionType, VariantType, NullType, StructType, BlobType } from "@elaraai/east";
+import type { PlatformFunction } from "@elaraai/east/internal";
+/**
+ * HTTP method variant type.
+ *
+ * Represents the HTTP request method for fetch operations.
+ * Supports standard HTTP methods: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS.
+ */
+export declare const FetchMethod: VariantType<{
+    readonly GET: NullType;
+    readonly POST: NullType;
+    readonly PUT: NullType;
+    readonly DELETE: NullType;
+    readonly PATCH: NullType;
+    readonly HEAD: NullType;
+    readonly OPTIONS: NullType;
+}>;
+/**
+ * HTTP request configuration structure.
+ *
+ * Complete configuration for making HTTP requests with custom methods,
+ * headers, and optional body content.
+ */
+export declare const FetchRequestConfig: StructType<{
+    readonly url: StringType;
+    readonly method: VariantType<{
+        readonly GET: NullType;
+        readonly POST: NullType;
+        readonly PUT: NullType;
+        readonly DELETE: NullType;
+        readonly PATCH: NullType;
+        readonly HEAD: NullType;
+        readonly OPTIONS: NullType;
+    }>;
+    readonly headers: DictType<StringType, StringType>;
+    readonly body: OptionType<StringType>;
+}>;
+/**
+ * HTTP response structure.
+ *
+ * Complete HTTP response including status code, headers, body, and success indicator.
+ * The `ok` field is true for status codes in the 200-299 range.
+ */
+export declare const FetchResponse: StructType<{
+    readonly status: IntegerType;
+    readonly statusText: StringType;
+    readonly headers: DictType<StringType, StringType>;
+    readonly body: StringType;
+    readonly ok: BooleanType;
+}>;
+/**
+ * Performs an HTTP GET request and returns the response body as a string.
+ *
+ * Makes a simple GET request to the specified URL and returns the response body text.
+ * This is a convenience function for basic GET requests without custom headers.
+ * Throws an error if the response status is not in the 200-299 range.
+ *
+ * This is a platform function for the East language, enabling HTTP GET requests
+ * in East programs running in a browser, through the browser's `fetch`.
+ *
+ * @param url - The URL to fetch (must be a valid HTTP/HTTPS URL)
+ * @returns The response body as a string
+ *
+ * @throws {EastError} When request fails:
+ * - Invalid URL
+ * - Network error, or a cross-origin request the server's CORS headers refuse
+ * - Non-2xx HTTP status code
+ *
+ * @example
+ * ```ts
+ * const fetchData = East.function([], StringType, $ => {
+ *     const data = $.let(Fetch.get("https://api.example.com/data"));
+ *     return data;
+ * });
+ * ```
+ */
+export declare const fetch_get: import("@elaraai/east").AsyncPlatformDefinition<[StringType], StringType>;
+/**
+ * Performs an HTTP GET request and returns the response body as binary data.
+ *
+ * Makes a simple GET request to the specified URL and returns the response body
+ * as raw bytes (Blob/Uint8Array). Useful for downloading binary files like images,
+ * PDFs, or database files.
+ * Throws an error if the response status is not in the 200-299 range.
+ *
+ * This is a platform function for the East language, enabling binary HTTP GET requests
+ * in East programs running in a browser, through the browser's `fetch`.
+ *
+ * @param url - The URL to fetch (must be a valid HTTP/HTTPS URL)
+ * @returns The response body as binary data (Blob)
+ *
+ * @throws {EastError} When request fails:
+ * - Invalid URL
+ * - Network error, or a cross-origin request the server's CORS headers refuse
+ * - Non-2xx HTTP status code
+ *
+ * @example
+ * ```ts
+ * const downloadFile = East.function([], BlobType, $ => {
+ *     const data = $.let(Fetch.getBytes("https://example.com/file.bin"));
+ *     return data;
+ * });
+ * ```
+ */
+export declare const fetch_get_bytes: import("@elaraai/east").AsyncPlatformDefinition<[StringType], BlobType>;
+/**
+ * Performs an HTTP POST request with a string body.
+ *
+ * Makes a POST request to the specified URL with the provided string body.
+ * Sets Content-Type header to "text/plain" by default. For more control over
+ * headers and methods, use {@link fetch_request}.
+ * Throws an error if the response status is not in the 200-299 range.
+ *
+ * This is a platform function for the East language, enabling HTTP POST requests
+ * in East programs running in a browser, through the browser's `fetch`.
+ *
+ * @param url - The URL to post to (must be a valid HTTP/HTTPS URL)
+ * @param body - The request body as a string
+ * @returns The response body as a string
+ *
+ * @throws {EastError} When request fails:
+ * - Invalid URL
+ * - Network error, or a cross-origin request the server's CORS headers refuse
+ * - Non-2xx HTTP status code
+ *
+ * @example
+ * ```ts
+ * const postData = East.function([], StringType, $ => {
+ *     const response = $.let(Fetch.post("https://api.example.com/submit", "data"));
+ *     return response;
+ * });
+ * ```
+ */
+export declare const fetch_post: import("@elaraai/east").AsyncPlatformDefinition<[StringType, StringType], StringType>;
+/**
+ * Performs a full HTTP request with custom configuration.
+ *
+ * Makes an HTTP request with complete control over method, headers, and body.
+ * Returns the full response including status, headers, and body. Unlike {@link fetch_get}
+ * and {@link fetch_post}, this does not throw on non-2xx status codes - check the `ok`
+ * field in the response instead.
+ *
+ * This is a platform function for the East language, enabling full HTTP requests
+ * in East programs running in a browser, through the browser's `fetch`.
+ *
+ * @param config - The request configuration (url, method, headers, optional body)
+ * @returns The complete HTTP response with status, headers, and body
+ *
+ * @throws {EastError} When request fails at the network level (not for HTTP errors)
+ *
+ * @example
+ * ```ts
+ * const makeRequest = East.function([], FetchResponse, $ => {
+ *     const config = $.let({
+ *         url: "https://api.example.com/data",
+ *         method: variant("GET", null),
+ *         headers: new Map([["Authorization", "Bearer token"]]),
+ *         body: none,
+ *     }, FetchRequestConfig);
+ *     return Fetch.request(config);
+ * });
+ * ```
+ *
+ * @remarks
+ * A browser sends a request only with the headers it allows a page to set,
+ * and a cross-origin response shows only the headers its server exposes.
+ */
+export declare const fetch_request: import("@elaraai/east").AsyncPlatformDefinition<[StructType<{
+    readonly url: StringType;
+    readonly method: VariantType<{
+        readonly GET: NullType;
+        readonly POST: NullType;
+        readonly PUT: NullType;
+        readonly DELETE: NullType;
+        readonly PATCH: NullType;
+        readonly HEAD: NullType;
+        readonly OPTIONS: NullType;
+    }>;
+    readonly headers: DictType<StringType, StringType>;
+    readonly body: OptionType<StringType>;
+}>], StructType<{
+    readonly status: IntegerType;
+    readonly statusText: StringType;
+    readonly headers: DictType<StringType, StringType>;
+    readonly body: StringType;
+    readonly ok: BooleanType;
+}>>;
+/**
+ * Browser implementation of fetch platform functions.
+ *
+ * Pass this array to {@link East.compileAsync} to enable fetch operations.
+ */
+declare const FetchImpl: PlatformFunction[];
+/**
+ * Grouped fetch platform functions.
+ *
+ * Provides HTTP client operations using the browser's fetch API.
+ *
+ * @example
+ * ```ts
+ * import { East, StringType } from "@elaraai/east";
+ * import { Fetch } from "@elaraai/east-web-std";
+ *
+ * const getData = East.function([], StringType, $ => {
+ *     const response = $.let(Fetch.get("https://api.example.com/data"));
+ *     return response;
+ * });
+ *
+ * const compiled = await East.compileAsync(getData.toIR(), Fetch.Implementation);
+ * await compiled();  // Returns response body as string
+ * ```
+ */
+export declare const Fetch: {
+    /**
+     * Performs an HTTP GET request and returns the response body.
+     *
+     * Makes a simple GET request to the specified URL and returns the response body text.
+     * Throws an error if the response status is not in the 200-299 range.
+     *
+     * @param url - The URL to fetch
+     * @returns The response body as a string
+     * @throws {EastError} When request fails or status is not 2xx
+     *
+     * @example
+     * ```ts
+     * const fetchData = East.function([], StringType, $ => {
+     *     return Fetch.get("https://api.example.com/data");
+     * });
+     *
+     * const compiled = await East.compileAsync(fetchData.toIR(), Fetch.Implementation);
+     * await compiled();  // Returns: response body as string
+     * ```
+     */
+    readonly get: import("@elaraai/east").AsyncPlatformDefinition<[StringType], StringType>;
+    /**
+     * Performs an HTTP GET request and returns the response body as binary data.
+     *
+     * Makes a simple GET request to the specified URL and returns the response body
+     * as raw bytes (Blob/Uint8Array). Useful for downloading binary files.
+     * Throws an error if the response status is not in the 200-299 range.
+     *
+     * @param url - The URL to fetch
+     * @returns The response body as binary data (Blob)
+     * @throws {EastError} When request fails or status is not 2xx
+     *
+     * @example
+     * ```ts
+     * const downloadFile = East.function([], BlobType, $ => {
+     *     return Fetch.getBytes("https://example.com/file.bin");
+     * });
+     *
+     * const compiled = await East.compileAsync(downloadFile.toIR(), Fetch.Implementation);
+     * await compiled();  // Returns: binary data as Uint8Array
+     * ```
+     */
+    readonly getBytes: import("@elaraai/east").AsyncPlatformDefinition<[StringType], BlobType>;
+    /**
+     * Performs an HTTP POST request with a string body.
+     *
+     * Makes a POST request to the specified URL with the provided string body.
+     * Sets Content-Type to "text/plain" by default.
+     * Throws an error if the response status is not in the 200-299 range.
+     *
+     * @param url - The URL to post to
+     * @param body - The request body as a string
+     * @returns The response body as a string
+     * @throws {EastError} When request fails or status is not 2xx
+     *
+     * @example
+     * ```ts
+     * const postData = East.function([], StringType, $ => {
+     *     return Fetch.post("https://api.example.com/submit", "data");
+     * });
+     *
+     * const compiled = await East.compileAsync(postData.toIR(), Fetch.Implementation);
+     * await compiled();  // Returns: response body as string
+     * ```
+     */
+    readonly post: import("@elaraai/east").AsyncPlatformDefinition<[StringType, StringType], StringType>;
+    /**
+     * Performs a full HTTP request with custom configuration.
+     *
+     * Makes an HTTP request with complete control over method, headers, and body.
+     * Returns the full response including status, headers, and body.
+     * Does not throw on non-2xx status - check the `ok` field instead.
+     *
+     * @param config - The request configuration
+     * @returns The complete HTTP response
+     * @throws {EastError} When request fails at the network level
+     *
+     * @example
+     * ```ts
+     * const makeRequest = East.function([], FetchResponse, $ => {
+     *     const config = $.let({
+     *         url: "https://api.example.com/data",
+     *         method: variant("GET", null),
+     *         headers: new Map(),
+     *         body: none,
+     *     }, FetchRequestConfig);
+     *     return Fetch.request(config);
+     * });
+     *
+     * const compiled = await East.compileAsync(makeRequest.toIR(), Fetch.Implementation);
+     * const response = await compiled();  // Returns: FetchResponse object
+     * ```
+     */
+    readonly request: import("@elaraai/east").AsyncPlatformDefinition<[StructType<{
+        readonly url: StringType;
+        readonly method: VariantType<{
+            readonly GET: NullType;
+            readonly POST: NullType;
+            readonly PUT: NullType;
+            readonly DELETE: NullType;
+            readonly PATCH: NullType;
+            readonly HEAD: NullType;
+            readonly OPTIONS: NullType;
+        }>;
+        readonly headers: DictType<StringType, StringType>;
+        readonly body: OptionType<StringType>;
+    }>], StructType<{
+        readonly status: IntegerType;
+        readonly statusText: StringType;
+        readonly headers: DictType<StringType, StringType>;
+        readonly body: StringType;
+        readonly ok: BooleanType;
+    }>>;
+    /**
+     * Browser implementation of fetch platform functions.
+     *
+     * Pass this to {@link East.compileAsync} to enable fetch operations.
+     */
+    readonly Implementation: PlatformFunction[];
+    /**
+     * Type definitions for fetch operations.
+     */
+    readonly Types: {
+        /**
+         * HTTP method variant type (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS).
+         */
+        readonly Method: VariantType<{
+            readonly GET: NullType;
+            readonly POST: NullType;
+            readonly PUT: NullType;
+            readonly DELETE: NullType;
+            readonly PATCH: NullType;
+            readonly HEAD: NullType;
+            readonly OPTIONS: NullType;
+        }>;
+        /**
+         * HTTP request configuration structure.
+         */
+        readonly RequestConfig: StructType<{
+            readonly url: StringType;
+            readonly method: VariantType<{
+                readonly GET: NullType;
+                readonly POST: NullType;
+                readonly PUT: NullType;
+                readonly DELETE: NullType;
+                readonly PATCH: NullType;
+                readonly HEAD: NullType;
+                readonly OPTIONS: NullType;
+            }>;
+            readonly headers: DictType<StringType, StringType>;
+            readonly body: OptionType<StringType>;
+        }>;
+        /**
+         * HTTP response structure.
+         */
+        readonly Response: StructType<{
+            readonly status: IntegerType;
+            readonly statusText: StringType;
+            readonly headers: DictType<StringType, StringType>;
+            readonly body: StringType;
+            readonly ok: BooleanType;
+        }>;
+    };
+};
+export { FetchImpl };
+//# sourceMappingURL=fetch.d.ts.map

package/dist/src/fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../../src/fetch.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAQ,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAA2C,MAAM,eAAe,CAAC;AACvL,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAG/D;;;;;GAKG;AACH,eAAO,MAAM,WAAW;;;;;;;;EAQtB,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;EAK7B,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,aAAa;;;;;;EAMxB,CAAC;AAKH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,SAAS,2EAA4D,CAAC;AAEnF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,eAAe,yEAAgE,CAAC;AAE7F;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,UAAU,uFAAyE,CAAC;AAEjG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;GAA2E,CAAC;AAEtG;;;;GAIG;AACH,QAAA,MAAM,SAAS,EAAE,gBAAgB,EAiGhC,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,KAAK;IACd;;;;;;;;;;;;;;;;;;;OAmBG;;IAGH;;;;;;;;;;;;;;;;;;;;OAoBG;;IAGH;;;;;;;;;;;;;;;;;;;;;OAqBG;;IAGH;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;;;;;;;;;;;;;;;;;;;;;IAGH;;;;OAIG;;IAGH;;OAEG;;QAEC;;WAEG;;;;;;;;;;QAGH;;WAEG;;;;;;;;;;;;;;;QAGH;;WAEG;;;;;;;;;CAGD,CAAC;AAGX,OAAO,EAAE,SAAS,EAAE,CAAC"}