@nilejs/client 1.0.1 → 1.1.0

package/dist/index.d.cts

@@ -1,3 +1,4 @@
+//#region src/types.d.ts
 /** Standard Nile API response shape */
 interface ExternalResponse<T = Record<string, unknown>> {
   status: boolean;
@@ -58,7 +59,6 @@ interface ExploreActionsResponse {
     visibility?: {
       rest?: boolean;
       rpc?: boolean;
-      ws?: boolean;
     };
   }>;
 }
@@ -75,6 +75,8 @@ interface NileClientConfig {
   headers?: Record<string, string>;
   /** Optional timeout in ms (default: 30000) */
   timeout?: number;
+  /** Socket settings for `client.socket`. The socket connects on first use. */
+  socket?: NileSocketConfig;
 }
 /** Options for individual fetch calls (body and method are managed internally) */
 interface FetchOptions extends Omit<RequestInit, "body" | "method"> {
@@ -97,7 +99,9 @@ interface UploadParams {
   fetchOptions?: FetchOptions;
 }
 /** Interface for the typed client */
-interface NileClient<TPayloads = Record<string, Record<string, unknown>>> {
+interface NileClient<TPayloads = Record<string, Record<string, unknown>>, TTopics extends TopicShape<TTopics> = SocketTopics> {
+  /** Typed topics over Socket.IO: `send`, `receive` and `close`. */
+  socket: NileSocketClient<TTopics>;
   /** Invoke an action with full type-safety for payload */
   invoke: <S extends keyof TPayloads & string, A extends keyof TPayloads[S] & string>(params: {
     service: S;
@@ -112,42 +116,16 @@ interface NileClient<TPayloads = Record<string, Record<string, unknown>>> {
   /** Upload files to an action via multipart form-data */
   upload: (params: UploadParams) => 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 invoke, explore, schema, and upload methods
- *
- * @example
- * const nile = createNileClient<ServicePayloads>({ baseUrl: "/api" });
- * const result = await nile.invoke({
- *   service: "tasks",
- *   action: "create",
- *   payload: { title: "Buy milk" }
- * });
- * if (result.isErr) {
- *   console.error(result.error);
- * } else {
- *   console.log(result.value);
- * }
- */
-export declare function createNileClient<TPayloads = Record<string, Record<string, unknown>>>(config: NileClientConfig): NileClient<TPayloads>;
-/** Let the runtime set the multipart boundary; retain the same action Result contract. */
-export declare function sendUploadRequest<T = Record<string, unknown>>(config: NileClientConfig, service: string, action: string, files: Record<string, File | File[]>, fields?: Record<string, string>, options?: FetchOptions): Promise<ClientResult<T>>;
-/**
- * Builds a FormData instance with RPC routing fields and file/field entries.
- * The server expects 'intent', 'service', 'action' as string fields.
- */
-export declare function buildFormData(service: string, action: string, files: Record<string, File | File[]>, fields?: Record<string, string>): FormData;
+//#endregion
+//#region src/socket-types.d.ts
+type WireJson = object | string | number | boolean | null;
 interface TopicContract {
-  data: object | string | number | boolean | null;
-  input?: object | string | number | boolean | null;
-  scope?: object | string | number | boolean | null;
+  data: WireJson;
+  input?: WireJson;
+  scope?: WireJson;
 }
 type TopicShape<T> = { [K in keyof T]: TopicContract; };
-type ActionShape<A> = { [S in keyof A]: { [K in keyof A[S]]: object; }; };
 type SocketTopics = Record<string, TopicContract>;
-type SocketActions = Record<string, Record<string, object>>;
 type SocketSelection<T, K extends keyof T> = {
   topic: K;
 } & (T[K] extends {
@@ -170,36 +148,97 @@ interface SocketMessage<K extends string, D> {
   id: string;
   topic: K;
   data: D;
-  scope?: object | string | number | boolean | null;
+  scope?: WireJson;
   time: string;
-}
-interface NileSocketClientConfig {
-  baseUrl: string;
+  /** Present when a client sent the message; absent for server messages. */
+  from?: {
+    connectionId: string;
+    userId?: string;
+  };
+}
+interface NileSocketConfig {
+  /** Socket server origin when it differs from `baseUrl`. Defaults to the origin of `baseUrl`. */
+  url?: string;
+  /** Socket.IO path. Default `/socket.io`; must match the server. */
   path?: string;
+  /** Connection and acknowledgement timeout in ms. Default 30000. */
   timeout?: number;
+  /** Sent when connecting, e.g. `{ token }`. A function is called again on every reconnect. */
   auth?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
-  onSubscriptionError?: (input: {
-    topic: string;
+  onConnect?: () => void;
+  onDisconnect?: (reason: string) => void;
+  /** Fires after a reconnect once active subscriptions are restored. */
+  onReconnect?: () => void;
+  /** A connection failure, or a subscription refused while restoring it after a reconnect. */
+  onError?: (error: {
     error: string;
+    topic?: string;
   }) => void;
 }
-interface NileSocketClient<A extends ActionShape<A>, T extends TopicShape<T>> {
-  invoke: <S extends keyof A & string, K extends keyof A[S] & string>(input: {
-    service: S;
-    action: K;
-    payload: A[S][K];
-  }) => Promise<ClientResult>;
+interface SocketSubscription {
+  topic: string;
+  /** Stop this listener; the server subscription ends when the last listener for it stops. */
+  unsubscribe: () => Promise<ClientResult<{
+    subscribed: boolean;
+  }>>;
+}
+interface NileSocketClient<T extends TopicShape<T> = SocketTopics> {
+  /** Send to a topic; the server checks the topic's `canSend` and validates the data. */
   send: <K extends keyof T & string>(input: SocketPublication<T, K>) => Promise<ClientResult<SocketMessage<K, T[K]["data"]>>>;
+  /** Subscribe to a topic and listen for its messages in one call. */
   receive: <K extends keyof T & string>(input: SocketSelection<T, K> & {
     onMessage: (message: SocketMessage<K, T[K]["data"]>) => void;
-  }) => Promise<ClientResult<{
-    unsubscribe: () => Promise<ClientResult<{
-      subscribed: boolean;
-    }>>;
-  }>>;
+  }) => Promise<ClientResult<SocketSubscription>>;
+  /** Disconnect and drop every listener. The client cannot reconnect afterwards. */
   close: () => void;
 }
-/** Own a lazy Socket.IO connection with no offline write buffering or automatic invocation retries. */
-export declare function createNileSocketClient<Actions extends ActionShape<Actions> = SocketActions, Topics extends TopicShape<Topics> = SocketTopics>(config: NileSocketClientConfig): NileSocketClient<Actions, Topics>;
-export type { ClientErr, ClientOk, ClientResult, ExploreActionsResponse, ExploreServicesResponse, ExternalResponse, FetchOptions, NileClient, NileClientConfig, NileIntentParams, NileSocketClient, NileSocketClientConfig, SocketActions, SocketMessage, SocketPublication, SocketSelection, SocketTopics, UploadParams, ValidationFailureData };
+//#endregion
+//#region src/create-client.d.ts
+/**
+ * Creates a type-safe Nile client for interacting with backend services.
+ *
+ * @param config - The client configuration including baseUrl
+ * @returns A factory object with invoke, explore, schema and upload methods, plus
+ *   `socket` for topics. The socket connects on its first `send` or `receive`.
+ *
+ * @example
+ * const nile = createNileClient<ServicePayloads>({ baseUrl: "/api" });
+ * const result = await nile.invoke({
+ *   service: "tasks",
+ *   action: "create",
+ *   payload: { title: "Buy milk" }
+ * });
+ * if (result.isErr) {
+ *   console.error(result.error);
+ * } else {
+ *   console.log(result.value);
+ * }
+ *
+ * const received = await nile.socket.receive({
+ *   topic: "tasks.updated",
+ *   onMessage: (message) => console.log(message.data),
+ * });
+ */
+export declare function createNileClient<TPayloads = Record<string, Record<string, unknown>>, TTopics extends TopicShape<TTopics> = SocketTopics>(config: NileClientConfig): NileClient<TPayloads, TTopics>;
+//#endregion
+//#region src/deprecated.d.ts
+/**
+ * Kept as a throwing stub so an upgrade fails with guidance instead of a
+ * missing export.
+ *
+ * @deprecated Use `createNileClient({ baseUrl, socket: { auth } })` and call
+ * `socket.send`, `socket.receive` and `socket.close` on the returned client.
+ */
+export declare function createNileSocketClient<Actions = unknown, Topics = unknown>(_config?: unknown): never;
+//#endregion
+//#region src/request.d.ts
+/** Let the runtime set the multipart boundary; retain the same action Result contract. */
+export declare function sendUploadRequest<T = Record<string, unknown>>(config: NileClientConfig, service: string, action: string, files: Record<string, File | File[]>, fields?: Record<string, string>, options?: FetchOptions): Promise<ClientResult<T>>;
+/**
+ * Builds a FormData instance with RPC routing fields and file/field entries.
+ * The server expects 'intent', 'service', 'action' as string fields.
+ */
+export declare function buildFormData(service: string, action: string, files: Record<string, File | File[]>, fields?: Record<string, string>): FormData;
+//#endregion
+export type { ClientErr, ClientOk, ClientResult, ExploreActionsResponse, ExploreServicesResponse, ExternalResponse, FetchOptions, NileClient, NileClientConfig, NileIntentParams, NileSocketClient, NileSocketConfig, SocketMessage, SocketPublication, SocketSelection, SocketSubscription, SocketTopics, TopicContract, UploadParams, ValidationFailureData };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+//#region src/types.d.ts
 /** Standard Nile API response shape */
 interface ExternalResponse<T = Record<string, unknown>> {
   status: boolean;
@@ -58,7 +59,6 @@ interface ExploreActionsResponse {
     visibility?: {
       rest?: boolean;
       rpc?: boolean;
-      ws?: boolean;
     };
   }>;
 }
@@ -75,6 +75,8 @@ interface NileClientConfig {
   headers?: Record<string, string>;
   /** Optional timeout in ms (default: 30000) */
   timeout?: number;
+  /** Socket settings for `client.socket`. The socket connects on first use. */
+  socket?: NileSocketConfig;
 }
 /** Options for individual fetch calls (body and method are managed internally) */
 interface FetchOptions extends Omit<RequestInit, "body" | "method"> {
@@ -97,7 +99,9 @@ interface UploadParams {
   fetchOptions?: FetchOptions;
 }
 /** Interface for the typed client */
-interface NileClient<TPayloads = Record<string, Record<string, unknown>>> {
+interface NileClient<TPayloads = Record<string, Record<string, unknown>>, TTopics extends TopicShape<TTopics> = SocketTopics> {
+  /** Typed topics over Socket.IO: `send`, `receive` and `close`. */
+  socket: NileSocketClient<TTopics>;
   /** Invoke an action with full type-safety for payload */
   invoke: <S extends keyof TPayloads & string, A extends keyof TPayloads[S] & string>(params: {
     service: S;
@@ -112,42 +116,16 @@ interface NileClient<TPayloads = Record<string, Record<string, unknown>>> {
   /** Upload files to an action via multipart form-data */
   upload: (params: UploadParams) => 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 invoke, explore, schema, and upload methods
- *
- * @example
- * const nile = createNileClient<ServicePayloads>({ baseUrl: "/api" });
- * const result = await nile.invoke({
- *   service: "tasks",
- *   action: "create",
- *   payload: { title: "Buy milk" }
- * });
- * if (result.isErr) {
- *   console.error(result.error);
- * } else {
- *   console.log(result.value);
- * }
- */
-export declare function createNileClient<TPayloads = Record<string, Record<string, unknown>>>(config: NileClientConfig): NileClient<TPayloads>;
-/** Let the runtime set the multipart boundary; retain the same action Result contract. */
-export declare function sendUploadRequest<T = Record<string, unknown>>(config: NileClientConfig, service: string, action: string, files: Record<string, File | File[]>, fields?: Record<string, string>, options?: FetchOptions): Promise<ClientResult<T>>;
-/**
- * Builds a FormData instance with RPC routing fields and file/field entries.
- * The server expects 'intent', 'service', 'action' as string fields.
- */
-export declare function buildFormData(service: string, action: string, files: Record<string, File | File[]>, fields?: Record<string, string>): FormData;
+//#endregion
+//#region src/socket-types.d.ts
+type WireJson = object | string | number | boolean | null;
 interface TopicContract {
-  data: object | string | number | boolean | null;
-  input?: object | string | number | boolean | null;
-  scope?: object | string | number | boolean | null;
+  data: WireJson;
+  input?: WireJson;
+  scope?: WireJson;
 }
 type TopicShape<T> = { [K in keyof T]: TopicContract; };
-type ActionShape<A> = { [S in keyof A]: { [K in keyof A[S]]: object; }; };
 type SocketTopics = Record<string, TopicContract>;
-type SocketActions = Record<string, Record<string, object>>;
 type SocketSelection<T, K extends keyof T> = {
   topic: K;
 } & (T[K] extends {
@@ -170,36 +148,97 @@ interface SocketMessage<K extends string, D> {
   id: string;
   topic: K;
   data: D;
-  scope?: object | string | number | boolean | null;
+  scope?: WireJson;
   time: string;
-}
-interface NileSocketClientConfig {
-  baseUrl: string;
+  /** Present when a client sent the message; absent for server messages. */
+  from?: {
+    connectionId: string;
+    userId?: string;
+  };
+}
+interface NileSocketConfig {
+  /** Socket server origin when it differs from `baseUrl`. Defaults to the origin of `baseUrl`. */
+  url?: string;
+  /** Socket.IO path. Default `/socket.io`; must match the server. */
   path?: string;
+  /** Connection and acknowledgement timeout in ms. Default 30000. */
   timeout?: number;
+  /** Sent when connecting, e.g. `{ token }`. A function is called again on every reconnect. */
   auth?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
-  onSubscriptionError?: (input: {
-    topic: string;
+  onConnect?: () => void;
+  onDisconnect?: (reason: string) => void;
+  /** Fires after a reconnect once active subscriptions are restored. */
+  onReconnect?: () => void;
+  /** A connection failure, or a subscription refused while restoring it after a reconnect. */
+  onError?: (error: {
     error: string;
+    topic?: string;
   }) => void;
 }
-interface NileSocketClient<A extends ActionShape<A>, T extends TopicShape<T>> {
-  invoke: <S extends keyof A & string, K extends keyof A[S] & string>(input: {
-    service: S;
-    action: K;
-    payload: A[S][K];
-  }) => Promise<ClientResult>;
+interface SocketSubscription {
+  topic: string;
+  /** Stop this listener; the server subscription ends when the last listener for it stops. */
+  unsubscribe: () => Promise<ClientResult<{
+    subscribed: boolean;
+  }>>;
+}
+interface NileSocketClient<T extends TopicShape<T> = SocketTopics> {
+  /** Send to a topic; the server checks the topic's `canSend` and validates the data. */
   send: <K extends keyof T & string>(input: SocketPublication<T, K>) => Promise<ClientResult<SocketMessage<K, T[K]["data"]>>>;
+  /** Subscribe to a topic and listen for its messages in one call. */
   receive: <K extends keyof T & string>(input: SocketSelection<T, K> & {
     onMessage: (message: SocketMessage<K, T[K]["data"]>) => void;
-  }) => Promise<ClientResult<{
-    unsubscribe: () => Promise<ClientResult<{
-      subscribed: boolean;
-    }>>;
-  }>>;
+  }) => Promise<ClientResult<SocketSubscription>>;
+  /** Disconnect and drop every listener. The client cannot reconnect afterwards. */
   close: () => void;
 }
-/** Own a lazy Socket.IO connection with no offline write buffering or automatic invocation retries. */
-export declare function createNileSocketClient<Actions extends ActionShape<Actions> = SocketActions, Topics extends TopicShape<Topics> = SocketTopics>(config: NileSocketClientConfig): NileSocketClient<Actions, Topics>;
-export type { ClientErr, ClientOk, ClientResult, ExploreActionsResponse, ExploreServicesResponse, ExternalResponse, FetchOptions, NileClient, NileClientConfig, NileIntentParams, NileSocketClient, NileSocketClientConfig, SocketActions, SocketMessage, SocketPublication, SocketSelection, SocketTopics, UploadParams, ValidationFailureData };
+//#endregion
+//#region src/create-client.d.ts
+/**
+ * Creates a type-safe Nile client for interacting with backend services.
+ *
+ * @param config - The client configuration including baseUrl
+ * @returns A factory object with invoke, explore, schema and upload methods, plus
+ *   `socket` for topics. The socket connects on its first `send` or `receive`.
+ *
+ * @example
+ * const nile = createNileClient<ServicePayloads>({ baseUrl: "/api" });
+ * const result = await nile.invoke({
+ *   service: "tasks",
+ *   action: "create",
+ *   payload: { title: "Buy milk" }
+ * });
+ * if (result.isErr) {
+ *   console.error(result.error);
+ * } else {
+ *   console.log(result.value);
+ * }
+ *
+ * const received = await nile.socket.receive({
+ *   topic: "tasks.updated",
+ *   onMessage: (message) => console.log(message.data),
+ * });
+ */
+export declare function createNileClient<TPayloads = Record<string, Record<string, unknown>>, TTopics extends TopicShape<TTopics> = SocketTopics>(config: NileClientConfig): NileClient<TPayloads, TTopics>;
+//#endregion
+//#region src/deprecated.d.ts
+/**
+ * Kept as a throwing stub so an upgrade fails with guidance instead of a
+ * missing export.
+ *
+ * @deprecated Use `createNileClient({ baseUrl, socket: { auth } })` and call
+ * `socket.send`, `socket.receive` and `socket.close` on the returned client.
+ */
+export declare function createNileSocketClient<Actions = unknown, Topics = unknown>(_config?: unknown): never;
+//#endregion
+//#region src/request.d.ts
+/** Let the runtime set the multipart boundary; retain the same action Result contract. */
+export declare function sendUploadRequest<T = Record<string, unknown>>(config: NileClientConfig, service: string, action: string, files: Record<string, File | File[]>, fields?: Record<string, string>, options?: FetchOptions): Promise<ClientResult<T>>;
+/**
+ * Builds a FormData instance with RPC routing fields and file/field entries.
+ * The server expects 'intent', 'service', 'action' as string fields.
+ */
+export declare function buildFormData(service: string, action: string, files: Record<string, File | File[]>, fields?: Record<string, string>): FormData;
+//#endregion
+export type { ClientErr, ClientOk, ClientResult, ExploreActionsResponse, ExploreServicesResponse, ExternalResponse, FetchOptions, NileClient, NileClientConfig, NileIntentParams, NileSocketClient, NileSocketConfig, SocketMessage, SocketPublication, SocketSelection, SocketSubscription, SocketTopics, TopicContract, UploadParams, ValidationFailureData };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,4 +1,4 @@
-// src/result.ts
+//#region src/result.ts
 /**
 * A successful client result. `data` mirrors `value` so code written for
 * earlier clients keeps working. `message` is present only when the server sent one.
@@ -27,7 +27,8 @@ function clientErr(error, details = null) {
 		data: null
 	};
 }
-// src/safe-try.ts
+//#endregion
+//#region src/safe-try.ts
 /**
 * Gracefully handles both synchronous and asynchronous operations by returning a result object.
 * This replaces the need for external slang-ts dependency and avoids try/catch boilerplate.
@@ -67,7 +68,8 @@ function safeTry(fn) {
 		};
 	}
 }
-// src/request.ts
+//#endregion
+//#region src/request.ts
 /** Send one action call; the deadline covers both fetch and reading its JSON body. */
 async function sendRequest(config, body, multipart, options) {
 	const { timeout = config.timeout ?? 3e4, headers, signal, ...fetchOptions } = options;
@@ -144,58 +146,24 @@ function buildFormData(service, action, files, fields) {
 function resolveError(error) {
 	return clientErr(error instanceof Error ? error.message : String(error));
 }
-// src/create-client.ts
-/**
-* Creates a type-safe Nile client for interacting with backend services.
-*
-* @param config - The client configuration including baseUrl
-* @returns A factory object with invoke, explore, schema, and upload methods
-*
-* @example
-* const nile = createNileClient<ServicePayloads>({ baseUrl: "/api" });
-* const result = await nile.invoke({
-*   service: "tasks",
-*   action: "create",
-*   payload: { title: "Buy milk" }
-* });
-* if (result.isErr) {
-*   console.error(result.error);
-* } else {
-*   console.log(result.value);
-* }
-*/
-function createNileClient(config) {
-	return {
-		/** Invoke a service action through the backend engine pipeline */
-		invoke: async (params) => {
-			const { service, action, payload, fetchOptions } = params;
-			return await sendNileRequest(config, "execute", service, action, payload, fetchOptions);
-		},
-		/** Discover available services and actions (supports "*" wildcard) */
-		explore: async (params) => {
-			const { service, action, fetchOptions } = params;
-			return await sendNileRequest(config, "explore", service, action, {}, fetchOptions);
-		},
-		/** Get action schemas as JSON Schema (supports "*" wildcard) */
-		schema: async (params) => {
-			const { service, action, fetchOptions } = params;
-			return await sendNileRequest(config, "schema", service, action, {}, fetchOptions);
-		},
-		/** Upload files to an action via multipart form-data */
-		upload: async (params) => {
-			const { service, action, files, fields, fetchOptions } = params;
-			return await sendUploadRequest(config, service, action, files, fields, fetchOptions);
-		}
-	};
+//#endregion
+//#region src/socket-client.ts
+/** The socket connects to an origin; any path in a URL would be read by Socket.IO as a namespace. */
+function socketOrigin(url) {
+	try {
+		return new URL(url).origin;
+	} catch {
+		return;
+	}
 }
-// src/socket-client.ts
-/** Own a lazy Socket.IO connection with no offline write buffering or automatic invocation retries. */
-function createNileSocketClient(config) {
+/** Own a lazy Socket.IO connection with no offline write buffering. */
+function createNileSocket(config) {
 	const timeout = config.timeout ?? 3e4;
 	if (!Number.isSafeInteger(timeout) || timeout < 1) throw new Error("Socket timeout must be positive");
 	let socket;
 	let connecting;
 	let closed = false;
+	let everConnected = false;
 	const listeners = /* @__PURE__ */ new Set();
 	const pending = /* @__PURE__ */ new Set();
 	const fail = (error) => clientErr(error);
@@ -244,7 +212,7 @@ function createNileSocketClient(config) {
 				continue;
 			}
 			const message = result.error;
-			settleCallback(() => config.onSubscriptionError?.({
+			settleCallback(() => config.onError?.({
 				topic: listener.topic,
 				error: message
 			}));
@@ -259,7 +227,7 @@ function createNileSocketClient(config) {
 				resolve(fail("Socket client is closed"));
 				return;
 			}
-			const current = socket ?? io(config.baseUrl, {
+			const current = socket ?? io(config.url ? socketOrigin(config.url) : void 0, {
 				path: config.path ?? "/socket.io",
 				autoConnect: false,
 				withCredentials: true,
@@ -270,11 +238,20 @@ function createNileSocketClient(config) {
 			});
 			if (!socket) {
 				socket = current;
-				current.on("disconnect", () => {
+				current.on("disconnect", (reason) => {
 					for (const cancel of [...pending]) cancel();
+					settleCallback(() => config.onDisconnect?.(reason));
 				});
 				current.on("connect", () => {
-					rejoin();
+					if (!everConnected) {
+						everConnected = true;
+						settleCallback(() => config.onConnect?.());
+						return;
+					}
+					rejoin().then(() => settleCallback(() => config.onReconnect?.()));
+				});
+				current.on("connect_error", () => {
+					settleCallback(() => config.onError?.({ error: "Socket connection failed" }));
 				});
 				current.on("nile:message", (message) => dispatchMessage(message, listeners));
 			}
@@ -302,7 +279,6 @@ function createNileSocketClient(config) {
 		return connecting;
 	};
 	return {
-		invoke: (input) => request("nile:invoke", input),
 		send: (input) => request("nile:send", input),
 		async receive(input) {
 			const listener = {
@@ -321,16 +297,19 @@ function createNileSocketClient(config) {
 				return fail(result.error);
 			}
 			listener.normalizedScope = result.value?.scope;
-			return clientOk({ unsubscribe: () => {
-				listener.active = false;
-				listeners.delete(listener);
-				const shared = [...listeners].some((item) => item.topic === listener.topic && stableScope(item.scope) === stableScope(listener.scope));
-				if (shared || closed) return Promise.resolve(clientOk({ subscribed: shared }));
-				return request("nile:unsubscribe", {
-					topic: listener.topic,
-					scope: listener.scope
-				});
-			} });
+			return clientOk({
+				topic: input.topic,
+				unsubscribe: () => {
+					listener.active = false;
+					listeners.delete(listener);
+					const shared = [...listeners].some((item) => item.topic === listener.topic && stableScope(item.scope) === stableScope(listener.scope));
+					if (shared || closed) return Promise.resolve(clientOk({ subscribed: shared }));
+					return request("nile:unsubscribe", {
+						topic: listener.topic,
+						scope: listener.scope
+					});
+				}
+			});
 		},
 		close() {
 			closed = true;
@@ -358,6 +337,82 @@ function dispatchMessage(message, listeners) {
 		Promise.resolve().then(() => listener.onMessage(message)).catch(() => void 0);
 	}
 }
+//#endregion
+//#region src/create-client.ts
+/**
+* Creates a type-safe Nile client for interacting with backend services.
+*
+* @param config - The client configuration including baseUrl
+* @returns A factory object with invoke, explore, schema and upload methods, plus
+*   `socket` for topics. The socket connects on its first `send` or `receive`.
+*
+* @example
+* const nile = createNileClient<ServicePayloads>({ baseUrl: "/api" });
+* const result = await nile.invoke({
+*   service: "tasks",
+*   action: "create",
+*   payload: { title: "Buy milk" }
+* });
+* if (result.isErr) {
+*   console.error(result.error);
+* } else {
+*   console.log(result.value);
+* }
+*
+* const received = await nile.socket.receive({
+*   topic: "tasks.updated",
+*   onMessage: (message) => console.log(message.data),
+* });
+*/
+function createNileClient(config) {
+	return {
+		socket: createNileSocket({
+			...config.socket,
+			url: config.socket?.url ?? config.baseUrl
+		}),
+		/** Invoke a service action through the backend engine pipeline */
+		invoke: async (params) => {
+			const { service, action, payload, fetchOptions } = params;
+			return await sendNileRequest(config, "execute", service, action, payload, fetchOptions);
+		},
+		/** Discover available services and actions (supports "*" wildcard) */
+		explore: async (params) => {
+			const { service, action, fetchOptions } = params;
+			return await sendNileRequest(config, "explore", service, action, {}, fetchOptions);
+		},
+		/** Get action schemas as JSON Schema (supports "*" wildcard) */
+		schema: async (params) => {
+			const { service, action, fetchOptions } = params;
+			return await sendNileRequest(config, "schema", service, action, {}, fetchOptions);
+		},
+		/** Upload files to an action via multipart form-data */
+		upload: async (params) => {
+			const { service, action, files, fields, fetchOptions } = params;
+			return await sendUploadRequest(config, service, action, files, fields, fetchOptions);
+		}
+	};
+}
+//#endregion
+//#region src/deprecated.ts
+const MIGRATION_MESSAGE = [
+	"createNileSocketClient was removed in @nilejs/client 1.1.0.",
+	"Create one client with createNileClient({ baseUrl, socket: { auth } })",
+	"and use nile.socket.send, nile.socket.receive and nile.socket.close.",
+	"Socket invoke is gone as well; call actions with nile.invoke over HTTP.",
+	"See https://nile-js.github.io/nile/guide/features/websockets/ and the",
+	"migration notes in packages/nile/docs/release-migration.md."
+].join(" ");
+/**
+* Kept as a throwing stub so an upgrade fails with guidance instead of a
+* missing export.
+*
+* @deprecated Use `createNileClient({ baseUrl, socket: { auth } })` and call
+* `socket.send`, `socket.receive` and `socket.close` on the returned client.
+*/
+function createNileSocketClient(_config) {
+	throw new Error(MIGRATION_MESSAGE);
+}
+//#endregion
 export { buildFormData, createNileClient, createNileSocketClient, sendUploadRequest };
 
 //# sourceMappingURL=index.js.map