@nilejs/client 0.0.3 → 1.0.1

package/README.md

@@ -1,12 +1,12 @@
 # @nilejs/client
 
-A standalone, type-safe client for the [Nile](https://github.com/nile-js/nile) backend framework.
+A type-safe frontend client for [Nile Js](https://nile-js.github.io/nile/) backends.
 
 ## 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).
+- **Type-safe:** Consumes shared or CLI-generated backend types for service, action and payload checking.
+- **Graceful Error Handling:** Returns the same Result pattern as the Nile Js backend (`isOk`, `isErr`, `value`, `error`) instead of throwing exceptions.
+- **Small:** HTTP calls use the platform `fetch`. The only runtime dependency is `socket.io-client`, for the socket client.
 - **Flexible:** Supports custom headers, credentials, and timeouts per request.
 
 ## Installation
@@ -38,16 +38,16 @@ const nile = createNileClient({
 ### 2. Invoke Actions
 
 ```typescript
-const { error, data } = await nile.invoke({
+const result = await nile.invoke({
   service: "tasks",
   action: "create",
   payload: { title: "Buy milk" },
 });
 
-if (error) {
-  console.error("Action failed:", error);
+if (result.isErr) {
+  console.error("Action failed:", result.error);
 } else {
-  console.log("Success:", data);
+  console.log("Success:", result.value);
 }
 ```
 
@@ -78,10 +78,18 @@ await nile.invoke({
 
 ```typescript
 // Explore services and actions
-const { data: services } = await nile.explore({ service: "*", action: "*" });
+const services = await nile.explore({ service: "*", action: "*" });
+
+if (services.isOk) {
+  console.log(services.value);
+}
 
 // Fetch action schemas
-const { data: schemas } = await nile.schema({ service: "tasks", action: "*" });
+const schemas = await nile.schema({ service: "tasks", action: "*" });
+
+if (schemas.isOk) {
+  console.log(schemas.value);
+}
 ```
 
 ## API
@@ -97,13 +105,103 @@ Returns a Nile client instance.
 
 ### Methods
 
-All methods return a `Promise<ClientResult<T>>` where `ClientResult<T>` is `{ error: string | null, data: T | null }`.
+All methods return a `Promise<ClientResult<T>>`. Calls never throw:
+
+- Success: `{ isOk: true, isErr: false, value: T, error: null, message? }`, where `message` is the server's success message for HTTP calls
+- Failure: `{ isOk: false, isErr: true, value: null, error: string, details }`, where `details` holds any data the server attached, such as validation issues. Network failures and timeouts arrive as failures too.
+
+Check `isErr` first, then read `error` or `value`. The older `data` field is still present as a deprecated alias (the value on success, `null` on failure) so existing code keeps working.
 
 - `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.
+Pass per-call settings in `fetchOptions`. Headers merge with the client’s configured headers; a per-call value overrides the same header regardless of case. Both `Headers` instances and header tuples are supported. The timeout covers reading the response body as well as connecting; an optional `signal` can cancel the call.
+
+```ts
+const controller = new AbortController();
+const result = await nile.invoke({
+  service: "tasks",
+  action: "create",
+  payload: { title: "Ship the next feature" },
+  fetchOptions: {
+    headers: { Authorization: "Bearer your-session-token" },
+    timeout: 5000,
+    signal: controller.signal,
+  },
+});
+```
+
+## Nile 1.0.3 responses
+
+HTTP responses contain exactly `status`, `message` and `data`. The client maps those into its existing Result API; it preserves custom messages, Zod’s prettified validation message, and generated diagnostic references. The default success message is `Action completed.`
+
+For a validation failure, `result.error` is the readable message and `result.details` contains `{ errorCode, issues }`. `ValidationFailureData` is exported for applications that narrow this unknown failure data. Other failures can carry different details, so check the shape before using it. Diagnostic failures may include `Error Code: <unique-code> - <message>` in the message. Treat the code as a reference to share with your backend logs; do not use it as a fixed error category.
+
+## Socket.IO actions and topics
+
+Create a separate socket client. It owns the connection; you do not pass a socket into each invocation. Use shared types, generated action types, or define your frontend contracts explicitly. Topic definitions and authorization policies must also be configured on the backend.
+
+```ts
+import { createNileSocketClient } from "@nilejs/client";
+import type { ServicePayloads } from "./generated/types";
+
+type Topics = {
+  "tasks.changed": {
+    data: { taskId: string; status: string };
+  };
+};
+
+const socket = createNileSocketClient<ServicePayloads, Topics>({
+  baseUrl: "http://localhost:8000",
+  auth: () => {
+    return { token: "your-session-token" };
+  },
+});
+
+const subscription = await socket.receive({
+  topic: "tasks.changed",
+  onMessage: (message) => {
+    console.log(message.data.taskId, message.data.status);
+  },
+});
+
+const result = await socket.invoke({
+  service: "tasks",
+  action: "create",
+  payload: { title: "Ship the next feature" },
+});
+
+const publication = await socket.send({
+  topic: "tasks.changed",
+  data: { taskId: "task-123", status: "done" },
+});
+
+if (subscription.isOk) {
+  await subscription.value.unsubscribe();
+}
+socket.close();
+```
+
+Keep the client open for as long as your application needs live updates. The connection is lazy, subscriptions rejoin after reconnecting, and disconnected writes are not buffered or retried automatically. Topic names, data and any required scope are checked from the supplied types; Nile validates them and enforces policies on the backend. The server can expose HTTP and sockets together. See [WebSockets](https://nile-js.github.io/nile/guide/features/websockets/) for server setup.
+
+## Uploads
+
+```ts
+const result = await nile.upload({
+  service: "documents",
+  action: "upload",
+  files: { document: file },
+  fields: { title: "Invoice" },
+  fetchOptions: { timeout: 60000 },
+});
+```
+
+Multipart calls share the same cancellation, deadline and Result behavior as JSON calls. Content-Type is set by the runtime so the multipart boundary is correct.
+
+## Compatibility
+
+Version 1.0.1 supports Nile 1.0.3 and 1.0.4 while keeping the existing HTTP and socket client APIs. It fixes header merging, cancellation and timeout cleanup; it does not add fields to Nile’s wire contract.
 
 ## License