@nilejs/client 1.0.0 → 1.1.0

package/dist/index.d.cts

@@ -5,6 +5,14 @@ interface ExternalResponse<T = Record<string, unknown>> {
   message: string;
   data: T;
 }
+/** Validation details returned by Nile HTTP actions; codes identify individual failures. */
+interface ValidationFailureData {
+  errorCode: string;
+  issues: Array<{
+    path: string;
+    message: string;
+  }>;
+}
 /** A successful call: read the action's data from `value`. */
 interface ClientOk<T> {
   isOk: true;
@@ -67,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"> {
@@ -89,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;
@@ -105,54 +117,15 @@ interface NileClient<TPayloads = Record<string, Record<string, unknown>>> {
   upload: (params: UploadParams) => Promise<ClientResult>;
 }
 //#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
- *
- * @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>;
-//#endregion
-//#region src/request.d.ts
-/**
- * Handles multipart form-data uploads to the Nile /services endpoint.
- * Builds a FormData body with RPC routing fields (intent, service, action),
- * user-provided fields, and file attachments.
- *
- * Content-Type header is intentionally omitted so the runtime sets the
- * correct multipart boundary automatically.
- */
-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 {
@@ -175,39 +148,97 @@ interface SocketMessage<K extends string, D> {
   id: string;
   topic: K;
   data: D;
-  scope?: object | string | number | boolean | null;
+  scope?: WireJson;
   time: string;
+  /** Present when a client sent the message; absent for server messages. */
+  from?: {
+    connectionId: string;
+    userId?: string;
+  };
 }
-interface NileSocketClientConfig {
-  baseUrl: 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;
 }
 //#endregion
-//#region src/socket-client.d.ts
-/** 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>;
+//#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, NileSocketClientConfig, SocketActions, SocketMessage, SocketPublication, SocketSelection, SocketTopics, UploadParams };
+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

@@ -5,6 +5,14 @@ interface ExternalResponse<T = Record<string, unknown>> {
   message: string;
   data: T;
 }
+/** Validation details returned by Nile HTTP actions; codes identify individual failures. */
+interface ValidationFailureData {
+  errorCode: string;
+  issues: Array<{
+    path: string;
+    message: string;
+  }>;
+}
 /** A successful call: read the action's data from `value`. */
 interface ClientOk<T> {
   isOk: true;
@@ -67,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"> {
@@ -89,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;
@@ -105,54 +117,15 @@ interface NileClient<TPayloads = Record<string, Record<string, unknown>>> {
   upload: (params: UploadParams) => Promise<ClientResult>;
 }
 //#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
- *
- * @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>;
-//#endregion
-//#region src/request.d.ts
-/**
- * Handles multipart form-data uploads to the Nile /services endpoint.
- * Builds a FormData body with RPC routing fields (intent, service, action),
- * user-provided fields, and file attachments.
- *
- * Content-Type header is intentionally omitted so the runtime sets the
- * correct multipart boundary automatically.
- */
-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 {
@@ -175,39 +148,97 @@ interface SocketMessage<K extends string, D> {
   id: string;
   topic: K;
   data: D;
-  scope?: object | string | number | boolean | null;
+  scope?: WireJson;
   time: string;
+  /** Present when a client sent the message; absent for server messages. */
+  from?: {
+    connectionId: string;
+    userId?: string;
+  };
 }
-interface NileSocketClientConfig {
-  baseUrl: 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;
 }
 //#endregion
-//#region src/socket-client.d.ts
-/** 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>;
+//#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, NileSocketClientConfig, SocketActions, SocketMessage, SocketPublication, SocketSelection, SocketTopics, UploadParams };
+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