@nilejs/client 0.0.1

package/README.md

@@ -0,0 +1,110 @@
+# @nilejs/client
+
+A standalone, type-safe client for the [Nile](https://github.com/nile-js/nile) backend framework.
+
+## Features
+
+- **Type-safe:** Generates and consumes types from your Nile backend for full compile-time payload validation.
+- **Graceful Error Handling:** Uses the result pattern `{ error, data }` instead of throwing exceptions.
+- **Zero Runtime Dependencies:** Built on raw `fetch` for maximum compatibility (uses `slang-ts` for safety).
+- **Flexible:** Supports custom headers, credentials, and timeouts per request.
+
+## Installation
+
+```bash
+# Using npm
+npm install @nilejs/client
+
+# Using pnpm
+pnpm add @nilejs/client
+
+# Using bun
+bun add @nilejs/client
+```
+
+## Usage
+
+### 1. Create a Client
+
+```typescript
+import { createNileClient } from "@nilejs/client";
+
+const nile = createNileClient({
+  baseUrl: "http://localhost:8000/api",
+  credentials: "include",
+});
+```
+
+### 2. Invoke Actions
+
+```typescript
+const { error, data } = await nile.invoke({
+  service: "tasks",
+  action: "create",
+  payload: { title: "Buy milk" },
+});
+
+if (error) {
+  console.error("Action failed:", error);
+} else {
+  console.log("Success:", data);
+}
+```
+
+### 3. Full Type Safety (Recommended)
+
+Generate your types using the Nile CLI:
+`nile generate schema --output ./src/generated`
+
+Then use the generated `ServicePayloads` map:
+
+```typescript
+import { createNileClient } from "@nilejs/client";
+import type { ServicePayloads } from "./generated/types";
+
+const nile = createNileClient<ServicePayloads>({ 
+  baseUrl: "/api" 
+});
+
+// Full autocomplete and type-checking for service, action, and payload
+await nile.invoke({
+  service: "tasks",
+  action: "create",
+  payload: { title: "Buy milk" }
+});
+```
+
+### 4. Discovery & Reflection
+
+```typescript
+// Explore services and actions
+const { data: services } = await nile.explore({ service: "*", action: "*" });
+
+// Fetch action schemas
+const { data: schemas } = await nile.schema({ service: "tasks", action: "*" });
+```
+
+## API
+
+### `createNileClient<T>(config)`
+
+Returns a Nile client instance.
+
+- `config.baseUrl`: The base URL of your Nile API (e.g., `http://localhost:8000/api`).
+- `config.credentials`: Request credentials (`include`, `omit`, `same-origin`).
+- `config.headers`: Global headers to include in every request.
+- `config.timeout`: Default request timeout in milliseconds (default: 30000).
+
+### Methods
+
+All methods return a `Promise<ClientResult<T>>` where `ClientResult<T>` is `{ error: string | null, data: T | null }`.
+
+- `invoke(params)`: Execute a specific service action.
+- `explore(params)`: Discover services/actions using wildcards.
+- `schema(params)`: Fetch action schemas as JSON Schema.
+
+Each method accepts an optional `timeout` and any standard fetch `headers` in its parameters.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,144 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createNileClient: () => createNileClient
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/safe-try.ts
+function safeTry(fn) {
+  try {
+    const result = fn();
+    if (result instanceof Promise) {
+      return result.then(
+        (value) => ({
+          isOk: true,
+          value,
+          isErr: false,
+          error: null
+        })
+      ).catch(
+        (error) => ({
+          isOk: false,
+          value: null,
+          isErr: true,
+          error
+        })
+      );
+    }
+    return { isOk: true, value: result, isErr: false, error: null };
+  } catch (error) {
+    return { isOk: false, value: null, isErr: true, error };
+  }
+}
+
+// src/request.ts
+async function sendNileRequest(config, intent, service, action, payload, options = {}) {
+  const { timeout = config.timeout ?? 3e4, ...fetchOptions } = options;
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+  const requestResult = await safeTry(async () => {
+    const response = await fetch(`${config.baseUrl}/services`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...config.headers,
+        ...fetchOptions.headers
+      },
+      credentials: config.credentials,
+      body: JSON.stringify({
+        intent,
+        service,
+        action,
+        payload: payload ?? {}
+      }),
+      signal: controller.signal,
+      ...fetchOptions
+    });
+    clearTimeout(timeoutId);
+    const json = await response.json();
+    return json;
+  });
+  if (requestResult.isErr) {
+    const error = requestResult.error;
+    let errorMsg = "An unknown error occurred";
+    if (error instanceof Error) {
+      errorMsg = error.name === "AbortError" ? "Request timed out" : error.message;
+    } else {
+      errorMsg = String(error);
+    }
+    return { error: errorMsg, data: null };
+  }
+  const result = requestResult.value;
+  if (!result.status) {
+    return { error: result.message, data: result.data };
+  }
+  return { error: null, data: result.data };
+}
+
+// src/create-client.ts
+function createNileClient(config) {
+  return {
+    /** Invoke a service action through the backend engine pipeline */
+    invoke: async (params) => {
+      const { service, action, payload, ...options } = params;
+      const result = await sendNileRequest(
+        config,
+        "execute",
+        service,
+        action,
+        payload,
+        options
+      );
+      return result;
+    },
+    /** Discover available services and actions (supports "*" wildcard) */
+    explore: async (params) => {
+      const { service, action, ...options } = params;
+      return await sendNileRequest(
+        config,
+        "explore",
+        service,
+        action,
+        {},
+        options
+      );
+    },
+    /** Get action schemas as JSON Schema (supports "*" wildcard) */
+    schema: async (params) => {
+      const { service, action, ...options } = params;
+      return await sendNileRequest(
+        config,
+        "schema",
+        service,
+        action,
+        {},
+        options
+      );
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createNileClient
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/safe-try.ts","../src/request.ts","../src/create-client.ts"],"sourcesContent":["export { createNileClient } from \"./create-client.js\";\nexport type * from \"./types.js\";\n","/**\n * Internal result type for safeTry\n */\nexport type SafeResult<T, E = unknown> =\n  | { isOk: true; value: T; isErr: false; error: null }\n  | { isOk: false; value: null; isErr: true; error: E };\n\n/**\n * Gracefully handles both synchronous and asynchronous operations by returning a result object.\n * This replaces the need for external slang-ts dependency and avoids try/catch boilerplate.\n *\n * @param fn - The function to execute (sync or async)\n * @returns A result object containing either the value or the error\n *\n * @example\n * const { isOk, value, error } = await safeTry(() => fetch(url));\n */\nexport function safeTry<T>(\n  fn: () => T | Promise<T>\n): Promise<SafeResult<T>> | SafeResult<T> {\n  try {\n    const result = fn();\n\n    if (result instanceof Promise) {\n      return result\n        .then(\n          (value): SafeResult<T> => ({\n            isOk: true,\n            value,\n            isErr: false,\n            error: null,\n          })\n        )\n        .catch(\n          (error): SafeResult<T> => ({\n            isOk: false,\n            value: null,\n            isErr: true,\n            error,\n          })\n        );\n    }\n\n    return { isOk: true, value: result, isErr: false, error: null };\n  } catch (error) {\n    return { isOk: false, value: null, isErr: true, error };\n  }\n}\n","import { safeTry } from \"./safe-try.js\";\nimport type {\n  ClientResult,\n  ExternalResponse,\n  FetchOptions,\n  NileClientConfig,\n} from \"./types.js\";\n\n/**\n * Handles communication with the Nile /services endpoint.\n * Uses fetch + safeTry for crash safety and consistent { error, data } results.\n */\nexport async function sendNileRequest<T = Record<string, unknown>>(\n  config: NileClientConfig,\n  intent: \"explore\" | \"execute\" | \"schema\",\n  service: string,\n  action: string,\n  payload: unknown,\n  options: FetchOptions = {}\n): Promise<ClientResult<T>> {\n  const { timeout = config.timeout ?? 30_000, ...fetchOptions } = options;\n\n  const controller = new AbortController();\n  const timeoutId = setTimeout(() => controller.abort(), timeout);\n\n  const requestResult = await safeTry(async () => {\n    const response = await fetch(`${config.baseUrl}/services`, {\n      method: \"POST\",\n      headers: {\n        \"Content-Type\": \"application/json\",\n        ...config.headers,\n        ...(fetchOptions.headers as Record<string, string>),\n      },\n      credentials: config.credentials,\n      body: JSON.stringify({\n        intent,\n        service,\n        action,\n        payload: payload ?? {},\n      }),\n      signal: controller.signal,\n      ...fetchOptions,\n    });\n\n    clearTimeout(timeoutId);\n\n    const json = (await response.json()) as ExternalResponse<T>;\n    return json;\n  });\n\n  if (requestResult.isErr) {\n    const error: unknown = requestResult.error;\n    let errorMsg = \"An unknown error occurred\";\n\n    if (error instanceof Error) {\n      errorMsg =\n        error.name === \"AbortError\" ? \"Request timed out\" : error.message;\n    } else {\n      errorMsg = String(error);\n    }\n\n    return { error: errorMsg, data: null };\n  }\n\n  const result = requestResult.value;\n\n  if (!result.status) {\n    return { error: result.message, data: result.data };\n  }\n\n  return { error: null, data: result.data };\n}\n","import { sendNileRequest } from \"./request.js\";\nimport type {\n  ClientResult,\n  FetchOptions,\n  NileClient,\n  NileClientConfig,\n} from \"./types.js\";\n\n/**\n * Creates a type-safe Nile client for interacting with backend services.\n *\n * @param config - The client configuration including baseUrl\n * @returns A factory object with execute, explore, and schema methods\n *\n * @example\n * const nile = createNileClient<ServicePayloads>({ baseUrl: \"/api\" });\n * const { error, data } = await nile.invoke({\n *   service: \"tasks\",\n *   action: \"create\",\n *   payload: { title: \"Buy milk\" }\n * });\n */\nexport function createNileClient<\n  TPayloads = Record<string, Record<string, unknown>>,\n>(config: NileClientConfig): NileClient<TPayloads> {\n  return {\n    /** Invoke a service action through the backend engine pipeline */\n    invoke: async <\n      S extends keyof TPayloads & string,\n      A extends keyof TPayloads[S] & string,\n    >(\n      params: { service: S; action: A; payload: TPayloads[S][A] } & FetchOptions\n    ) => {\n      const { service, action, payload, ...options } = params;\n      const result = await sendNileRequest<Record<string, unknown>>(\n        config,\n        \"execute\",\n        service,\n        action,\n        payload,\n        options\n      );\n      return result as ClientResult;\n    },\n\n    /** Discover available services and actions (supports \"*\" wildcard) */\n    explore: async (\n      params: { service: string; action: string } & FetchOptions\n    ) => {\n      const { service, action, ...options } = params;\n      return await sendNileRequest(\n        config,\n        \"explore\",\n        service,\n        action,\n        {},\n        options\n      );\n    },\n\n    /** Get action schemas as JSON Schema (supports \"*\" wildcard) */\n    schema: async (\n      params: { service: string; action: string } & FetchOptions\n    ) => {\n      const { service, action, ...options } = params;\n      return await sendNileRequest(\n        config,\n        \"schema\",\n        service,\n        action,\n        {},\n        options\n      );\n    },\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,66 @@
+/** Standard Nile API response shape */
+interface ExternalResponse<T = Record<string, unknown>> {
+    status: boolean;
+    message: string;
+    data: T;
+}
+/** Result pattern: { error, data } (graceful failure over throwing) */
+interface ClientResult<T = Record<string, unknown>> {
+    error: string | null;
+    data: T | null;
+}
+/** Nile intent payload structure */
+interface NileIntentParams<T = Record<string, unknown>> {
+    service: string;
+    action: string;
+    payload?: T;
+}
+/** Client configuration */
+interface NileClientConfig {
+    baseUrl: string;
+    credentials?: "include" | "omit" | "same-origin";
+    headers?: Record<string, string>;
+    /** Optional timeout in ms (default: 30000) */
+    timeout?: number;
+}
+/** Options for individual fetch calls */
+interface FetchOptions extends Omit<RequestInit, "body" | "method"> {
+    timeout?: number;
+}
+/** Interface for the typed client */
+interface NileClient<TPayloads = Record<string, Record<string, unknown>>> {
+    /** Invoke an action with full type-safety for payload */
+    invoke: <S extends keyof TPayloads & string, A extends keyof TPayloads[S] & string>(params: {
+        service: S;
+        action: A;
+        payload: TPayloads[S][A];
+    } & FetchOptions) => Promise<ClientResult>;
+    /** Discover services/actions (supports "*" wildcard) */
+    explore: (params: {
+        service: string;
+        action: string;
+    } & FetchOptions) => Promise<ClientResult>;
+    /** Get action schemas as JSON Schema (supports "*" wildcard) */
+    schema: (params: {
+        service: string;
+        action: string;
+    } & FetchOptions) => Promise<ClientResult>;
+}
+
+/**
+ * Creates a type-safe Nile client for interacting with backend services.
+ *
+ * @param config - The client configuration including baseUrl
+ * @returns A factory object with execute, explore, and schema methods
+ *
+ * @example
+ * const nile = createNileClient<ServicePayloads>({ baseUrl: "/api" });
+ * const { error, data } = await nile.invoke({
+ *   service: "tasks",
+ *   action: "create",
+ *   payload: { title: "Buy milk" }
+ * });
+ */
+declare function createNileClient<TPayloads = Record<string, Record<string, unknown>>>(config: NileClientConfig): NileClient<TPayloads>;
+
+export { type ClientResult, type ExternalResponse, type FetchOptions, type NileClient, type NileClientConfig, type NileIntentParams, createNileClient };

package/dist/index.d.ts

@@ -0,0 +1,66 @@
+/** Standard Nile API response shape */
+interface ExternalResponse<T = Record<string, unknown>> {
+    status: boolean;
+    message: string;
+    data: T;
+}
+/** Result pattern: { error, data } (graceful failure over throwing) */
+interface ClientResult<T = Record<string, unknown>> {
+    error: string | null;
+    data: T | null;
+}
+/** Nile intent payload structure */
+interface NileIntentParams<T = Record<string, unknown>> {
+    service: string;
+    action: string;
+    payload?: T;
+}
+/** Client configuration */
+interface NileClientConfig {
+    baseUrl: string;
+    credentials?: "include" | "omit" | "same-origin";
+    headers?: Record<string, string>;
+    /** Optional timeout in ms (default: 30000) */
+    timeout?: number;
+}
+/** Options for individual fetch calls */
+interface FetchOptions extends Omit<RequestInit, "body" | "method"> {
+    timeout?: number;
+}
+/** Interface for the typed client */
+interface NileClient<TPayloads = Record<string, Record<string, unknown>>> {
+    /** Invoke an action with full type-safety for payload */
+    invoke: <S extends keyof TPayloads & string, A extends keyof TPayloads[S] & string>(params: {
+        service: S;
+        action: A;
+        payload: TPayloads[S][A];
+    } & FetchOptions) => Promise<ClientResult>;
+    /** Discover services/actions (supports "*" wildcard) */
+    explore: (params: {
+        service: string;
+        action: string;
+    } & FetchOptions) => Promise<ClientResult>;
+    /** Get action schemas as JSON Schema (supports "*" wildcard) */
+    schema: (params: {
+        service: string;
+        action: string;
+    } & FetchOptions) => Promise<ClientResult>;
+}
+
+/**
+ * Creates a type-safe Nile client for interacting with backend services.
+ *
+ * @param config - The client configuration including baseUrl
+ * @returns A factory object with execute, explore, and schema methods
+ *
+ * @example
+ * const nile = createNileClient<ServicePayloads>({ baseUrl: "/api" });
+ * const { error, data } = await nile.invoke({
+ *   service: "tasks",
+ *   action: "create",
+ *   payload: { title: "Buy milk" }
+ * });
+ */
+declare function createNileClient<TPayloads = Record<string, Record<string, unknown>>>(config: NileClientConfig): NileClient<TPayloads>;
+
+export { type ClientResult, type ExternalResponse, type FetchOptions, type NileClient, type NileClientConfig, type NileIntentParams, createNileClient };

package/dist/index.js

@@ -0,0 +1,117 @@
+// src/safe-try.ts
+function safeTry(fn) {
+  try {
+    const result = fn();
+    if (result instanceof Promise) {
+      return result.then(
+        (value) => ({
+          isOk: true,
+          value,
+          isErr: false,
+          error: null
+        })
+      ).catch(
+        (error) => ({
+          isOk: false,
+          value: null,
+          isErr: true,
+          error
+        })
+      );
+    }
+    return { isOk: true, value: result, isErr: false, error: null };
+  } catch (error) {
+    return { isOk: false, value: null, isErr: true, error };
+  }
+}
+
+// src/request.ts
+async function sendNileRequest(config, intent, service, action, payload, options = {}) {
+  const { timeout = config.timeout ?? 3e4, ...fetchOptions } = options;
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+  const requestResult = await safeTry(async () => {
+    const response = await fetch(`${config.baseUrl}/services`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...config.headers,
+        ...fetchOptions.headers
+      },
+      credentials: config.credentials,
+      body: JSON.stringify({
+        intent,
+        service,
+        action,
+        payload: payload ?? {}
+      }),
+      signal: controller.signal,
+      ...fetchOptions
+    });
+    clearTimeout(timeoutId);
+    const json = await response.json();
+    return json;
+  });
+  if (requestResult.isErr) {
+    const error = requestResult.error;
+    let errorMsg = "An unknown error occurred";
+    if (error instanceof Error) {
+      errorMsg = error.name === "AbortError" ? "Request timed out" : error.message;
+    } else {
+      errorMsg = String(error);
+    }
+    return { error: errorMsg, data: null };
+  }
+  const result = requestResult.value;
+  if (!result.status) {
+    return { error: result.message, data: result.data };
+  }
+  return { error: null, data: result.data };
+}
+
+// src/create-client.ts
+function createNileClient(config) {
+  return {
+    /** Invoke a service action through the backend engine pipeline */
+    invoke: async (params) => {
+      const { service, action, payload, ...options } = params;
+      const result = await sendNileRequest(
+        config,
+        "execute",
+        service,
+        action,
+        payload,
+        options
+      );
+      return result;
+    },
+    /** Discover available services and actions (supports "*" wildcard) */
+    explore: async (params) => {
+      const { service, action, ...options } = params;
+      return await sendNileRequest(
+        config,
+        "explore",
+        service,
+        action,
+        {},
+        options
+      );
+    },
+    /** Get action schemas as JSON Schema (supports "*" wildcard) */
+    schema: async (params) => {
+      const { service, action, ...options } = params;
+      return await sendNileRequest(
+        config,
+        "schema",
+        service,
+        action,
+        {},
+        options
+      );
+    }
+  };
+}
+export {
+  createNileClient
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/safe-try.ts","../src/request.ts","../src/create-client.ts"],"sourcesContent":["/**\n * Internal result type for safeTry\n */\nexport type SafeResult<T, E = unknown> =\n  | { isOk: true; value: T; isErr: false; error: null }\n  | { isOk: false; value: null; isErr: true; error: E };\n\n/**\n * Gracefully handles both synchronous and asynchronous operations by returning a result object.\n * This replaces the need for external slang-ts dependency and avoids try/catch boilerplate.\n *\n * @param fn - The function to execute (sync or async)\n * @returns A result object containing either the value or the error\n *\n * @example\n * const { isOk, value, error } = await safeTry(() => fetch(url));\n */\nexport function safeTry<T>(\n  fn: () => T | Promise<T>\n): Promise<SafeResult<T>> | SafeResult<T> {\n  try {\n    const result = fn();\n\n    if (result instanceof Promise) {\n      return result\n        .then(\n          (value): SafeResult<T> => ({\n            isOk: true,\n            value,\n            isErr: false,\n            error: null,\n          })\n        )\n        .catch(\n          (error): SafeResult<T> => ({\n            isOk: false,\n            value: null,\n            isErr: true,\n            error,\n          })\n        );\n    }\n\n    return { isOk: true, value: result, isErr: false, error: null };\n  } catch (error) {\n    return { isOk: false, value: null, isErr: true, error };\n  }\n}\n","import { safeTry } from \"./safe-try.js\";\nimport type {\n  ClientResult,\n  ExternalResponse,\n  FetchOptions,\n  NileClientConfig,\n} from \"./types.js\";\n\n/**\n * Handles communication with the Nile /services endpoint.\n * Uses fetch + safeTry for crash safety and consistent { error, data } results.\n */\nexport async function sendNileRequest<T = Record<string, unknown>>(\n  config: NileClientConfig,\n  intent: \"explore\" | \"execute\" | \"schema\",\n  service: string,\n  action: string,\n  payload: unknown,\n  options: FetchOptions = {}\n): Promise<ClientResult<T>> {\n  const { timeout = config.timeout ?? 30_000, ...fetchOptions } = options;\n\n  const controller = new AbortController();\n  const timeoutId = setTimeout(() => controller.abort(), timeout);\n\n  const requestResult = await safeTry(async () => {\n    const response = await fetch(`${config.baseUrl}/services`, {\n      method: \"POST\",\n      headers: {\n        \"Content-Type\": \"application/json\",\n        ...config.headers,\n        ...(fetchOptions.headers as Record<string, string>),\n      },\n      credentials: config.credentials,\n      body: JSON.stringify({\n        intent,\n        service,\n        action,\n        payload: payload ?? {},\n      }),\n      signal: controller.signal,\n      ...fetchOptions,\n    });\n\n    clearTimeout(timeoutId);\n\n    const json = (await response.json()) as ExternalResponse<T>;\n    return json;\n  });\n\n  if (requestResult.isErr) {\n    const error: unknown = requestResult.error;\n    let errorMsg = \"An unknown error occurred\";\n\n    if (error instanceof Error) {\n      errorMsg =\n        error.name === \"AbortError\" ? \"Request timed out\" : error.message;\n    } else {\n      errorMsg = String(error);\n    }\n\n    return { error: errorMsg, data: null };\n  }\n\n  const result = requestResult.value;\n\n  if (!result.status) {\n    return { error: result.message, data: result.data };\n  }\n\n  return { error: null, data: result.data };\n}\n","import { sendNileRequest } from \"./request.js\";\nimport type {\n  ClientResult,\n  FetchOptions,\n  NileClient,\n  NileClientConfig,\n} from \"./types.js\";\n\n/**\n * Creates a type-safe Nile client for interacting with backend services.\n *\n * @param config - The client configuration including baseUrl\n * @returns A factory object with execute, explore, and schema methods\n *\n * @example\n * const nile = createNileClient<ServicePayloads>({ baseUrl: \"/api\" });\n * const { error, data } = await nile.invoke({\n *   service: \"tasks\",\n *   action: \"create\",\n *   payload: { title: \"Buy milk\" }\n * });\n */\nexport function createNileClient<\n  TPayloads = Record<string, Record<string, unknown>>,\n>(config: NileClientConfig): NileClient<TPayloads> {\n  return {\n    /** Invoke a service action through the backend engine pipeline */\n    invoke: async <\n      S extends keyof TPayloads & string,\n      A extends keyof TPayloads[S] & string,\n    >(\n      params: { service: S; action: A; payload: TPayloads[S][A] } & FetchOptions\n    ) => {\n      const { service, action, payload, ...options } = params;\n      const result = await sendNileRequest<Record<string, unknown>>(\n        config,\n        \"execute\",\n        service,\n        action,\n        payload,\n        options\n      );\n      return result as ClientResult;\n    },\n\n    /** Discover available services and actions (supports \"*\" wildcard) */\n    explore: async (\n      params: { service: string; action: string } & FetchOptions\n    ) => {\n      const { service, action, ...options } = params;\n      return await sendNileRequest(\n        config,\n        \"explore\",\n        service,\n        action,\n        {},\n        options\n      );\n    },\n\n    /** Get action schemas as JSON Schema (supports \"*\" wildcard) */\n    schema: async (\n      params: { service: string; action: string } & FetchOptions\n    ) => {\n      const { service, action, ...options } = params;\n      return await sendNileRequest(\n        config,\n        \"schema\",\n        service,\n        action,\n        {},\n        options\n      );\n    },\n  };\n}\n"],"mappings":";AAiBO,SAAS,QACd,IACwC;AACxC,MAAI;AACF,UAAM,SAAS,GAAG;AAElB,QAAI,kBAAkB,SAAS;AAC7B,aAAO,OACJ;AAAA,QACC,CAAC,WAA0B;AAAA,UACzB,MAAM;AAAA,UACN;AAAA,UACA,OAAO;AAAA,UACP,OAAO;AAAA,QACT;AAAA,MACF,EACC;AAAA,QACC,CAAC,WAA0B;AAAA,UACzB,MAAM;AAAA,UACN,OAAO;AAAA,UACP,OAAO;AAAA,UACP;AAAA,QACF;AAAA,MACF;AAAA,IACJ;AAEA,WAAO,EAAE,MAAM,MAAM,OAAO,QAAQ,OAAO,OAAO,OAAO,KAAK;AAAA,EAChE,SAAS,OAAO;AACd,WAAO,EAAE,MAAM,OAAO,OAAO,MAAM,OAAO,MAAM,MAAM;AAAA,EACxD;AACF;;;ACnCA,eAAsB,gBACpB,QACA,QACA,SACA,QACA,SACA,UAAwB,CAAC,GACC;AAC1B,QAAM,EAAE,UAAU,OAAO,WAAW,KAAQ,GAAG,aAAa,IAAI;AAEhE,QAAM,aAAa,IAAI,gBAAgB;AACvC,QAAM,YAAY,WAAW,MAAM,WAAW,MAAM,GAAG,OAAO;AAE9D,QAAM,gBAAgB,MAAM,QAAQ,YAAY;AAC9C,UAAM,WAAW,MAAM,MAAM,GAAG,OAAO,OAAO,aAAa;AAAA,MACzD,QAAQ;AAAA,MACR,SAAS;AAAA,QACP,gBAAgB;AAAA,QAChB,GAAG,OAAO;AAAA,QACV,GAAI,aAAa;AAAA,MACnB;AAAA,MACA,aAAa,OAAO;AAAA,MACpB,MAAM,KAAK,UAAU;AAAA,QACnB;AAAA,QACA;AAAA,QACA;AAAA,QACA,SAAS,WAAW,CAAC;AAAA,MACvB,CAAC;AAAA,MACD,QAAQ,WAAW;AAAA,MACnB,GAAG;AAAA,IACL,CAAC;AAED,iBAAa,SAAS;AAEtB,UAAM,OAAQ,MAAM,SAAS,KAAK;AAClC,WAAO;AAAA,EACT,CAAC;AAED,MAAI,cAAc,OAAO;AACvB,UAAM,QAAiB,cAAc;AACrC,QAAI,WAAW;AAEf,QAAI,iBAAiB,OAAO;AAC1B,iBACE,MAAM,SAAS,eAAe,sBAAsB,MAAM;AAAA,IAC9D,OAAO;AACL,iBAAW,OAAO,KAAK;AAAA,IACzB;AAEA,WAAO,EAAE,OAAO,UAAU,MAAM,KAAK;AAAA,EACvC;AAEA,QAAM,SAAS,cAAc;AAE7B,MAAI,CAAC,OAAO,QAAQ;AAClB,WAAO,EAAE,OAAO,OAAO,SAAS,MAAM,OAAO,KAAK;AAAA,EACpD;AAEA,SAAO,EAAE,OAAO,MAAM,MAAM,OAAO,KAAK;AAC1C;;;ACjDO,SAAS,iBAEd,QAAiD;AACjD,SAAO;AAAA;AAAA,IAEL,QAAQ,OAIN,WACG;AACH,YAAM,EAAE,SAAS,QAAQ,SAAS,GAAG,QAAQ,IAAI;AACjD,YAAM,SAAS,MAAM;AAAA,QACnB;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,MACF;AACA,aAAO;AAAA,IACT;AAAA;AAAA,IAGA,SAAS,OACP,WACG;AACH,YAAM,EAAE,SAAS,QAAQ,GAAG,QAAQ,IAAI;AACxC,aAAO,MAAM;AAAA,QACX;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA,CAAC;AAAA,QACD;AAAA,MACF;AAAA,IACF;AAAA;AAAA,IAGA,QAAQ,OACN,WACG;AACH,YAAM,EAAE,SAAS,QAAQ,GAAG,QAAQ,IAAI;AACxC,aAAO,MAAM;AAAA,QACX;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA,CAAC;AAAA,QACD;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACF;","names":[]}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@nilejs/client",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Standalone, type-safe client for Nile backend framework",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
+  },
+  "devDependencies": {
+    "typescript": "^5",
+    "tsup": "^8.5.1"
+  }
+}