@meshtrade/api-web 1.30.0 → 1.31.0

package/dist/meshtrade/iam/user/v1/service_web_meshts.js

@@ -7,28 +7,87 @@ exports.UserServiceWeb = void 0;
 const connect_1 = require("@connectrpc/connect");
 const connect_web_1 = require("@connectrpc/connect-web");
 const service_pb_1 = require("./service_pb");
-const config_1 = require("../../../common/config");
-const validation_1 = require("../../../common/validation");
-const connectInterceptors_1 = require("../../../common/connectInterceptors");
+const service_pb_2 = require("./service_pb");
+const config_1 = require("../../../config");
+const protovalidate_1 = require("@bufbuild/protovalidate");
+const interceptors_1 = require("../../../interceptors");
 /**
  * Web client for interacting with the meshtrade.iam.user.v1 user v1 API resource service.
- * Uses Connect-ES with gRPC-Web transport for browser-compatible gRPC communication.
+ * Uses Connect-ES with gRPC-Web transport for browser-based communication.
+ *
+ * Supports flexible authentication modes using functional options pattern:
+ *
+ * 1. **No Authentication** (public APIs):
+ *    ```typescript
+ *    const client = new UserServiceWeb(
+ *      WithServerUrl("http://localhost:10000")
+ *    );
+ *    ```
+ *
+ * 2. **API Key Authentication** (backend services):
+ *    ```typescript
+ *    const client = new UserServiceWeb(
+ *      WithAPIKey("your-api-key"),
+ *      WithGroup("groups/01ARZ3NDEKTSV4YWVF8F5BH32"),
+ *      WithServerUrl("https://api.example.com")
+ *    );
+ *    ```
+ *
+ * 3. **JWT Token Authentication** (Next.js frontend with user session):
+ *    ```typescript
+ *    const client = new UserServiceWeb(
+ *      WithJWTAccessToken("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."),
+ *      WithServerUrl("https://api.example.com")
+ *    );
+ *    ```
+ *
+ * 4. **JWT with Group Context** (user session with specific group):
+ *    ```typescript
+ *    const client = new UserServiceWeb(
+ *      WithJWTAccessToken("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."),
+ *      WithGroup("groups/01ARZ3NDEKTSV4YWVF8F5BH32"),
+ *      WithServerUrl("https://api.example.com")
+ *    );
+ *    ```
+ *
+ * Available options:
+ * - `WithAPIKey(key)` - API key authentication (mutually exclusive with JWT)
+ * - `WithJWTAccessToken(token)` - JWT authentication (mutually exclusive with API key)
+ * - `WithGroup(group)` - Group context (optional, works with both auth modes)
+ * - `WithServerUrl(url)` - Custom server URL (optional, defaults to production)
  */
 class UserServiceWeb {
     /**
      * Constructs an instance of UserServiceWeb.
-     * @param {ConfigOpts} [config] - Optional configuration for the client.
-     * @param {Interceptor[]} [interceptors] - For internal use by `withGroup`.
+     *
+     * Uses functional options pattern for flexible configuration:
+     * - `WithAPIKey(key)` - API key authentication
+     * - `WithJWTAccessToken(token)` - JWT authentication
+     * - `WithGroup(group)` - Group context (optional)
+     * - `WithServerUrl(url)` - Custom server URL (optional)
+     *
+     * @param {...ClientOption} opts - Variable number of configuration options
      */
-    constructor(config, interceptors) {
-        this._config = (0, config_1.getConfigFromOpts)(config);
-        this._interceptors = interceptors || [];
-        // Create the gRPC-Web transport with interceptors
+    constructor(...opts) {
+        // Build configuration from options
+        this._config = (0, config_1.buildConfigFromOptions)(...opts);
+        // Initialize validator for request validation
+        this._validator = (0, protovalidate_1.createValidator)();
+        this._interceptors = [];
+        this._interceptors.push((0, interceptors_1.createLoggingInterceptor)());
+        if (this._config.apiKey) {
+            this._interceptors.push((0, interceptors_1.createApiKeyInterceptor)(this._config.apiKey));
+        }
+        if (this._config.jwtToken) {
+            this._interceptors.push((0, interceptors_1.createJwtInterceptor)(this._config.jwtToken));
+        }
+        if (this._config.group) {
+            this._interceptors.push((0, interceptors_1.createGroupInterceptor)(this._config.group));
+        }
+        // Create the gRPC-Web transport for browser with interceptors
         const transport = (0, connect_web_1.createGrpcWebTransport)({
             baseUrl: this._config.apiServerURL,
             interceptors: this._interceptors,
-            // Enable credentials (cookies) for cross-origin requests
-            fetch: (input, init) => globalThis.fetch(input, { ...init, credentials: 'include' }),
         });
         // Construct the Connect-ES client
         this._client = (0, connect_1.createClient)(service_pb_1.UserService, transport);
@@ -37,26 +96,36 @@ class UserServiceWeb {
      * Returns a new client instance configured to send the specified group
      * resource name in the request headers for subsequent API calls.
      *
+     * This method creates a new client with the same authentication configuration
+     * but with the group context updated to the specified value.
+     *
+     * **Compatibility**: Works with all authentication modes:
+     * - **API key auth**: Creates new client with API key + new group
+     * - **JWT auth**: Creates new client with JWT + new group
+     * - **No auth**: Creates new client with standalone group interceptor
+     *
      * @param {string} group - The operating group context to inject into the request
      *                         in the format `groups/{ulid}` where {ulid} is a 26-character ULID.
      *                         Example: 'groups/01ARZ3NDEKTSV4YWVF8F5BH32'
      * @returns {UserServiceWeb} A new, configured instance of the client.
-     * @throws {Error} If the group format is invalid (validation occurs in createGroupInterceptor)
+     * @throws {Error} If the group format is invalid
      */
     withGroup(group) {
-        // Check if a group interceptor already exists.
-        // Group interceptors are identified by having a 'groupContext' property
-        const hasGroupInterceptor = this._interceptors.some((interceptor) => interceptor.groupContext !== undefined);
-        if (hasGroupInterceptor) {
-            throw new Error("Attempted to set group context twice. A group has already been set for this client instance.");
-        }
-        // Create a new interceptor for the group context
-        const groupInterceptor = (0, connectInterceptors_1.createGroupInterceptor)(group);
-        // Return a new client instance with the existing interceptors plus the new one
-        return new UserServiceWeb(this._config, [
-            ...this._interceptors,
-            groupInterceptor,
-        ]);
+        // Build new options array with existing auth and updated group
+        const newOpts = [];
+        // Add server URL
+        newOpts.push((0, config_1.WithServerUrl)(this._config.apiServerURL));
+        // Add authentication (preserve existing mode)
+        if (this._config.apiKey) {
+            newOpts.push((0, config_1.WithAPIKey)(this._config.apiKey));
+        }
+        else if (this._config.jwtToken) {
+            newOpts.push((0, config_1.WithJWTAccessToken)(this._config.jwtToken));
+        }
+        // Add the new group
+        newOpts.push((0, config_1.WithGroup)(group));
+        // Return a new client instance with updated configuration
+        return new UserServiceWeb(...newOpts);
     }
     /**
      * Performs assignrolestouser operation on user.
@@ -65,7 +134,14 @@ class UserServiceWeb {
      */
     assignRolesToUser(request) {
         // Validate request
-        (0, validation_1.validateRequest)(request);
+        const result = this._validator.validate(service_pb_2.AssignRolesToUserRequestSchema, request);
+        if (result.kind === "invalid") {
+            const violations = result.violations.map(v => `${v.field.toString()}: ${v.message}`).join("; ");
+            throw new Error(`Validation failed: ${violations}`);
+        }
+        else if (result.kind === "error") {
+            throw result.error;
+        }
         return this._client.assignRolesToUser(request);
     }
     /**
@@ -75,7 +151,14 @@ class UserServiceWeb {
      */
     revokeRolesFromUser(request) {
         // Validate request
-        (0, validation_1.validateRequest)(request);
+        const result = this._validator.validate(service_pb_2.RevokeRolesFromUserRequestSchema, request);
+        if (result.kind === "invalid") {
+            const violations = result.violations.map(v => `${v.field.toString()}: ${v.message}`).join("; ");
+            throw new Error(`Validation failed: ${violations}`);
+        }
+        else if (result.kind === "error") {
+            throw result.error;
+        }
         return this._client.revokeRolesFromUser(request);
     }
     /**
@@ -85,7 +168,14 @@ class UserServiceWeb {
      */
     getUser(request) {
         // Validate request
-        (0, validation_1.validateRequest)(request);
+        const result = this._validator.validate(service_pb_2.GetUserRequestSchema, request);
+        if (result.kind === "invalid") {
+            const violations = result.violations.map(v => `${v.field.toString()}: ${v.message}`).join("; ");
+            throw new Error(`Validation failed: ${violations}`);
+        }
+        else if (result.kind === "error") {
+            throw result.error;
+        }
         return this._client.getUser(request);
     }
     /**
@@ -95,7 +185,14 @@ class UserServiceWeb {
      */
     getUserByEmail(request) {
         // Validate request
-        (0, validation_1.validateRequest)(request);
+        const result = this._validator.validate(service_pb_2.GetUserByEmailRequestSchema, request);
+        if (result.kind === "invalid") {
+            const violations = result.violations.map(v => `${v.field.toString()}: ${v.message}`).join("; ");
+            throw new Error(`Validation failed: ${violations}`);
+        }
+        else if (result.kind === "error") {
+            throw result.error;
+        }
         return this._client.getUserByEmail(request);
     }
     /**
@@ -105,7 +202,14 @@ class UserServiceWeb {
      */
     listUsers(request) {
         // Validate request
-        (0, validation_1.validateRequest)(request);
+        const result = this._validator.validate(service_pb_2.ListUsersRequestSchema, request);
+        if (result.kind === "invalid") {
+            const violations = result.violations.map(v => `${v.field.toString()}: ${v.message}`).join("; ");
+            throw new Error(`Validation failed: ${violations}`);
+        }
+        else if (result.kind === "error") {
+            throw result.error;
+        }
         return this._client.listUsers(request);
     }
     /**
@@ -115,7 +219,14 @@ class UserServiceWeb {
      */
     searchUsers(request) {
         // Validate request
-        (0, validation_1.validateRequest)(request);
+        const result = this._validator.validate(service_pb_2.SearchUsersRequestSchema, request);
+        if (result.kind === "invalid") {
+            const violations = result.violations.map(v => `${v.field.toString()}: ${v.message}`).join("; ");
+            throw new Error(`Validation failed: ${violations}`);
+        }
+        else if (result.kind === "error") {
+            throw result.error;
+        }
         return this._client.searchUsers(request);
     }
     /**
@@ -125,7 +236,14 @@ class UserServiceWeb {
      */
     createUser(request) {
         // Validate request
-        (0, validation_1.validateRequest)(request);
+        const result = this._validator.validate(service_pb_2.CreateUserRequestSchema, request);
+        if (result.kind === "invalid") {
+            const violations = result.violations.map(v => `${v.field.toString()}: ${v.message}`).join("; ");
+            throw new Error(`Validation failed: ${violations}`);
+        }
+        else if (result.kind === "error") {
+            throw result.error;
+        }
         return this._client.createUser(request);
     }
     /**
@@ -135,7 +253,14 @@ class UserServiceWeb {
      */
     updateUser(request) {
         // Validate request
-        (0, validation_1.validateRequest)(request);
+        const result = this._validator.validate(service_pb_2.UpdateUserRequestSchema, request);
+        if (result.kind === "invalid") {
+            const violations = result.violations.map(v => `${v.field.toString()}: ${v.message}`).join("; ");
+            throw new Error(`Validation failed: ${violations}`);
+        }
+        else if (result.kind === "error") {
+            throw result.error;
+        }
         return this._client.updateUser(request);
     }
 }

package/dist/meshtrade/iam/user/v1/user_pb.d.ts

@@ -33,12 +33,20 @@ export type User = Message<"meshtrade.iam.user.v1.User"> & {
      * @generated from field: string owner = 2;
      */
     owner: string;
+    /**
+     *
+     * Ownership hiearchy of groups that have access to this resource in the format groups/{group_id}.
+     * System set on creation.
+     *
+     * @generated from field: repeated string owners = 3;
+     */
+    owners: string[];
     /**
      *
      * The unique email address of this user.
      * This field is required on creation and must be a valid email format.
      *
-     * @generated from field: string email = 3;
+     * @generated from field: string email = 4;
      */
     email: string;
     /**
@@ -47,7 +55,7 @@ export type User = Message<"meshtrade.iam.user.v1.User"> & {
      * prepended by the name of the group in which they have been assigned that role.
      * e.g. groups/{ULIDv2}/roles/{role}, where role is a value of the meshtrade.iam.role.v1.Role enum.
      *
-     * @generated from field: repeated string roles = 4;
+     * @generated from field: repeated string roles = 5;
      */
     roles: string[];
 };

package/dist/meshtrade/iam/user/v1/user_pb.js

@@ -9,7 +9,7 @@ const validate_pb_1 = require("../../../../buf/validate/validate_pb");
 /**
  * Describes the file meshtrade/iam/user/v1/user.proto.
  */
-exports.file_meshtrade_iam_user_v1_user = (0, codegenv2_1.fileDesc)("CiBtZXNodHJhZGUvaWFtL3VzZXIvdjEvdXNlci5wcm90bxIVbWVzaHRyYWRlLmlhbS51c2VyLnYxIosDCgRVc2VyErQBCgRuYW1lGAEgASgJQqUBukihAboBnQEKFG5hbWUuZm9ybWF0Lm9wdGlvbmFsEjJuYW1lIG11c3QgYmUgZW1wdHkgb3IgaW4gdGhlIGZvcm1hdCB1c2Vycy97VUxJRHYyfRpRc2l6ZSh0aGlzKSA9PSAwIHx8IHRoaXMubWF0Y2hlcygnXnVzZXJzL1swMTIzNDU2Nzg5QUJDREVGR0hKS01OUFFSU1RWV1hZWl17MjZ9JCcpEksKBW93bmVyGAIgASgJQjy6SDnIAQFyNDIvXmdyb3Vwcy9bMDEyMzQ1Njc4OUFCQ0RFRkdISktNTlBRUlNUVldYWVpdezI2fSSYASESGQoFZW1haWwYAyABKAlCCrpIB8gBAXICYAESZAoFcm9sZXMYBCADKAlCVbpIUpIBTyJNcksQLxgwMkVeZ3JvdXBzL1swMTIzNDU2Nzg5QUJDREVGR0hKS01OUFFSU1RWV1hZWl17MjZ9L3JvbGVzL1sxLTldWzAtOV17Niw3fSRCTwocY28ubWVzaHRyYWRlLmFwaS5pYW0udXNlci52MVovZ2l0aHViLmNvbS9tZXNodHJhZGUvYXBpL2dvL2lhbS91c2VyL3YxO3VzZXJfdjFiBnByb3RvMw", [validate_pb_1.file_buf_validate_validate]);
+exports.file_meshtrade_iam_user_v1_user = (0, codegenv2_1.fileDesc)("CiBtZXNodHJhZGUvaWFtL3VzZXIvdjEvdXNlci5wcm90bxIVbWVzaHRyYWRlLmlhbS51c2VyLnYxItsDCgRVc2VyErQBCgRuYW1lGAEgASgJQqUBukihAboBnQEKFG5hbWUuZm9ybWF0Lm9wdGlvbmFsEjJuYW1lIG11c3QgYmUgZW1wdHkgb3IgaW4gdGhlIGZvcm1hdCB1c2Vycy97VUxJRHYyfRpRc2l6ZSh0aGlzKSA9PSAwIHx8IHRoaXMubWF0Y2hlcygnXnVzZXJzL1swMTIzNDU2Nzg5QUJDREVGR0hKS01OUFFSU1RWV1hZWl17MjZ9JCcpEksKBW93bmVyGAIgASgJQjy6SDnIAQFyNDIvXmdyb3Vwcy9bMDEyMzQ1Njc4OUFCQ0RFRkdISktNTlBRUlNUVldYWVpdezI2fSSYASESTgoGb3duZXJzGAMgAygJQj66SDuSATgiNnI0Mi9eZ3JvdXBzL1swMTIzNDU2Nzg5QUJDREVGR0hKS01OUFFSU1RWV1hZWl17MjZ9JJgBIRIZCgVlbWFpbBgEIAEoCUIKukgHyAEBcgJgARJkCgVyb2xlcxgFIAMoCUJVukhSkgFPIk1ySxAvGDAyRV5ncm91cHMvWzAxMjM0NTY3ODlBQkNERUZHSEpLTU5QUVJTVFZXWFlaXXsyNn0vcm9sZXMvWzEtOV1bMC05XXs2LDd9JEJPChxjby5tZXNodHJhZGUuYXBpLmlhbS51c2VyLnYxWi9naXRodWIuY29tL21lc2h0cmFkZS9hcGkvZ28vaWFtL3VzZXIvdjE7dXNlcl92MWIGcHJvdG8z", [validate_pb_1.file_buf_validate_validate]);
 /**
  * Describes the message meshtrade.iam.user.v1.User.
  * Use `create(UserSchema)` to create a new message.

package/dist/meshtrade/{common/connectInterceptors.d.ts → interceptors/index.d.ts}

@@ -1,23 +1,9 @@
 /**
- * Connect-ES interceptors for the Meshtrade API client (Web/Browser).
+ * Connect-ES interceptors for the Meshtrade API client.
  *
  * Provides interceptor utilities for use with @connectrpc/connect clients,
- * including group context injection for multi-tenant operations.
- *
- * ## Authentication in Browser Environments
- *
- * The Web SDK uses browser-native cookie-based authentication via the
- * `credentials: 'include'` fetch option. This automatically sends HTTP-only
- * cookies (like AccessToken) with each request, which is the standard and
- * secure authentication pattern for browser applications.
- *
- * Unlike the Node.js SDK which supports explicit API key and JWT interceptors,
- * the Web SDK relies on the browser's automatic cookie handling. This is why
- * this module only provides group context and logging interceptors - authentication
- * is handled implicitly by the browser's cookie mechanism.
- *
- * For backend/server-side authentication needs, use the Node.js SDK instead
- * (@meshtrade/api-node), which provides explicit API key and JWT token support.
+ * including authentication (API key, JWT) and group context injection for
+ * multi-tenant operations.
  */
 import { Interceptor } from "@connectrpc/connect";
 /**
@@ -54,6 +40,26 @@ import { Interceptor } from "@connectrpc/connect";
 export declare function createGroupInterceptor(group: string): Interceptor & {
     groupContext: string;
 };
+/**
+ * Creates a Connect-ES interceptor that injects API key authentication.
+ *
+ * @param apiKey - The API key for authentication
+ * @returns An interceptor that adds x-api-key header
+ * @throws {Error} If apiKey is empty
+ */
+export declare function createApiKeyInterceptor(apiKey: string): Interceptor & {
+    apiKeyAuth: true;
+};
+/**
+ * Creates a Connect-ES interceptor that injects JWT token authentication.
+ *
+ * @param jwtToken - The JWT token from the user's session
+ * @returns An interceptor that adds AccessToken cookie
+ * @throws {Error} If jwtToken is empty
+ */
+export declare function createJwtInterceptor(jwtToken: string): Interceptor & {
+    jwtAuth: true;
+};
 /**
  * Creates a logging interceptor that logs all requests and responses.
  * Useful for debugging and development.

package/dist/meshtrade/{common/connectInterceptors.js → interceptors/index.js}

@@ -1,29 +1,33 @@
 "use strict";
 /**
- * Connect-ES interceptors for the Meshtrade API client (Web/Browser).
+ * Connect-ES interceptors for the Meshtrade API client.
  *
  * Provides interceptor utilities for use with @connectrpc/connect clients,
- * including group context injection for multi-tenant operations.
- *
- * ## Authentication in Browser Environments
- *
- * The Web SDK uses browser-native cookie-based authentication via the
- * `credentials: 'include'` fetch option. This automatically sends HTTP-only
- * cookies (like AccessToken) with each request, which is the standard and
- * secure authentication pattern for browser applications.
- *
- * Unlike the Node.js SDK which supports explicit API key and JWT interceptors,
- * the Web SDK relies on the browser's automatic cookie handling. This is why
- * this module only provides group context and logging interceptors - authentication
- * is handled implicitly by the browser's cookie mechanism.
- *
- * For backend/server-side authentication needs, use the Node.js SDK instead
- * (@meshtrade/api-node), which provides explicit API key and JWT token support.
+ * including authentication (API key, JWT) and group context injection for
+ * multi-tenant operations.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createGroupInterceptor = createGroupInterceptor;
+exports.createApiKeyInterceptor = createApiKeyInterceptor;
+exports.createJwtInterceptor = createJwtInterceptor;
 exports.createLoggingInterceptor = createLoggingInterceptor;
-const validation_1 = require("./validation");
+/**
+ * HTTP header names for authentication.
+ * Must match the server-side header constants.
+ */
+const API_KEY_HEADER = "x-api-key";
+const GROUP_HEADER = "x-group";
+const COOKIE_HEADER = "cookie";
+const ACCESS_TOKEN_COOKIE_NAME = "AccessToken";
+/**
+ * Validates if a resource name follows the groups/{ulid} format.
+ *
+ * @param resourceName - The resource name string to validate
+ * @returns true if the resource name is a valid group resource name, false otherwise
+ */
+function isValidGroupResourceName(resourceName) {
+    return /^groups\/[0-9A-Z]{26}$/.test(resourceName);
+}
 /**
  * Creates a Connect-ES interceptor that injects operating group context
  * into API requests by adding an `x-group` header.
@@ -57,21 +61,54 @@ const validation_1 = require("./validation");
  */
 function createGroupInterceptor(group) {
     // Validate the group resource name format
-    if (!(0, validation_1.isValidGroupResourceName)(group)) {
+    if (!isValidGroupResourceName(group)) {
         throw new Error(`Invalid group format: "${group}". Group must be in the format "groups/{ulid}" ` +
             `where {ulid} is a 26-character ULID (e.g., "groups/01ARZ3NDEKTSV4YWVF8F5BH32").`);
     }
     // Create the interceptor function
     const interceptor = (next) => async (req) => {
-        // Add the x-group header to the request
-        req.header.set("x-group", group);
-        // Call the next interceptor in the chain
+        req.header.set(GROUP_HEADER, group);
         return await next(req);
     };
     // Add a marker property so we can identify group interceptors
     // This is used in the withGroup method to prevent double-setting
     return Object.assign(interceptor, { groupContext: group });
 }
+/**
+ * Creates a Connect-ES interceptor that injects API key authentication.
+ *
+ * @param apiKey - The API key for authentication
+ * @returns An interceptor that adds x-api-key header
+ * @throws {Error} If apiKey is empty
+ */
+function createApiKeyInterceptor(apiKey) {
+    if (!apiKey || apiKey.trim() === "") {
+        throw new Error("API key cannot be empty");
+    }
+    const interceptor = (next) => async (req) => {
+        req.header.set(API_KEY_HEADER, apiKey);
+        return await next(req);
+    };
+    return Object.assign(interceptor, { apiKeyAuth: true });
+}
+/**
+ * Creates a Connect-ES interceptor that injects JWT token authentication.
+ *
+ * @param jwtToken - The JWT token from the user's session
+ * @returns An interceptor that adds AccessToken cookie
+ * @throws {Error} If jwtToken is empty
+ */
+function createJwtInterceptor(jwtToken) {
+    if (!jwtToken || jwtToken.trim() === "") {
+        throw new Error("JWT token cannot be empty");
+    }
+    const interceptor = (next) => async (req) => {
+        const cookieValue = `${ACCESS_TOKEN_COOKIE_NAME}=${jwtToken}`;
+        req.header.set(COOKIE_HEADER, cookieValue);
+        return await next(req);
+    };
+    return Object.assign(interceptor, { jwtAuth: true });
+}
 /**
  * Creates a logging interceptor that logs all requests and responses.
  * Useful for debugging and development.
@@ -96,7 +133,7 @@ function createLoggingInterceptor() {
             headers[key] = value;
         });
         // Log the request
-        console.log(`[Connect] ${req.method.name} request:`, {
+        console.debug(`[Connect] ${req.method.name} request:`, {
             service: req.service.typeName,
             method: req.method.name,
             headers,
@@ -105,7 +142,7 @@ function createLoggingInterceptor() {
             // Call the next interceptor and get the response
             const response = await next(req);
             // Log successful response
-            console.log(`[Connect] ${req.method.name} response:`, {
+            console.debug(`[Connect] ${req.method.name} response:`, {
                 service: req.service.typeName,
                 method: req.method.name,
                 status: "success",

package/dist/meshtrade/ledger/transaction/v1/service_web_meshts.d.ts

@@ -1,29 +1,84 @@
-import { Interceptor } from "@connectrpc/connect";
 import { GetTransactionStateRequest, GetTransactionStateResponse, MonitorTransactionStateRequest, MonitorTransactionStateResponse } from "./service_pb";
-import { ConfigOpts } from "../../../common/config";
+import { ClientOption } from "../../../config";
 /**
  * Web client for interacting with the meshtrade.ledger.transaction.v1 transaction v1 API resource service.
- * Uses Connect-ES with gRPC-Web transport for browser-compatible gRPC communication.
+ * Uses Connect-ES with gRPC-Web transport for browser-based communication.
+ *
+ * Supports flexible authentication modes using functional options pattern:
+ *
+ * 1. **No Authentication** (public APIs):
+ *    ```typescript
+ *    const client = new TransactionServiceWeb(
+ *      WithServerUrl("http://localhost:10000")
+ *    );
+ *    ```
+ *
+ * 2. **API Key Authentication** (backend services):
+ *    ```typescript
+ *    const client = new TransactionServiceWeb(
+ *      WithAPIKey("your-api-key"),
+ *      WithGroup("groups/01ARZ3NDEKTSV4YWVF8F5BH32"),
+ *      WithServerUrl("https://api.example.com")
+ *    );
+ *    ```
+ *
+ * 3. **JWT Token Authentication** (Next.js frontend with user session):
+ *    ```typescript
+ *    const client = new TransactionServiceWeb(
+ *      WithJWTAccessToken("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."),
+ *      WithServerUrl("https://api.example.com")
+ *    );
+ *    ```
+ *
+ * 4. **JWT with Group Context** (user session with specific group):
+ *    ```typescript
+ *    const client = new TransactionServiceWeb(
+ *      WithJWTAccessToken("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."),
+ *      WithGroup("groups/01ARZ3NDEKTSV4YWVF8F5BH32"),
+ *      WithServerUrl("https://api.example.com")
+ *    );
+ *    ```
+ *
+ * Available options:
+ * - `WithAPIKey(key)` - API key authentication (mutually exclusive with JWT)
+ * - `WithJWTAccessToken(token)` - JWT authentication (mutually exclusive with API key)
+ * - `WithGroup(group)` - Group context (optional, works with both auth modes)
+ * - `WithServerUrl(url)` - Custom server URL (optional, defaults to production)
  */
 export declare class TransactionServiceWeb {
     private _client;
     private readonly _config;
     private readonly _interceptors;
+    private readonly _validator;
     /**
      * Constructs an instance of TransactionServiceWeb.
-     * @param {ConfigOpts} [config] - Optional configuration for the client.
-     * @param {Interceptor[]} [interceptors] - For internal use by `withGroup`.
+     *
+     * Uses functional options pattern for flexible configuration:
+     * - `WithAPIKey(key)` - API key authentication
+     * - `WithJWTAccessToken(token)` - JWT authentication
+     * - `WithGroup(group)` - Group context (optional)
+     * - `WithServerUrl(url)` - Custom server URL (optional)
+     *
+     * @param {...ClientOption} opts - Variable number of configuration options
      */
-    constructor(config?: ConfigOpts, interceptors?: Interceptor[]);
+    constructor(...opts: ClientOption[]);
     /**
      * Returns a new client instance configured to send the specified group
      * resource name in the request headers for subsequent API calls.
      *
+     * This method creates a new client with the same authentication configuration
+     * but with the group context updated to the specified value.
+     *
+     * **Compatibility**: Works with all authentication modes:
+     * - **API key auth**: Creates new client with API key + new group
+     * - **JWT auth**: Creates new client with JWT + new group
+     * - **No auth**: Creates new client with standalone group interceptor
+     *
      * @param {string} group - The operating group context to inject into the request
      *                         in the format `groups/{ulid}` where {ulid} is a 26-character ULID.
      *                         Example: 'groups/01ARZ3NDEKTSV4YWVF8F5BH32'
      * @returns {TransactionServiceWeb} A new, configured instance of the client.
-     * @throws {Error} If the group format is invalid (validation occurs in createGroupInterceptor)
+     * @throws {Error} If the group format is invalid
      */
     withGroup(group: string): TransactionServiceWeb;
     /**