@meshtrade/api-node 1.30.2 → 1.31.0

package/dist/meshtrade/config/index.js

@@ -0,0 +1,210 @@
+"use strict";
+/**
+ * Configuration options for Meshtrade API clients using functional options pattern.
+ *
+ * Supports flexible authentication modes with optional group context:
+ *
+ * 1. **No Authentication** (public APIs):
+ *    ```typescript
+ *    const client = new ServiceNode(
+ *      WithServerUrl("http://localhost:10000")
+ *    );
+ *    ```
+ *
+ * 2. **API Key Authentication** (backend services):
+ *    ```typescript
+ *    const client = new ServiceNode(
+ *      WithAPIKey("your-api-key"),
+ *      WithGroup("groups/01ARZ3NDEKTSV4YWVF8F5BH32"),
+ *      WithServerUrl("https://api.example.com")
+ *    );
+ *    ```
+ *
+ * 3. **JWT Token Authentication** (Next.js backend with user session):
+ *    ```typescript
+ *    const client = new ServiceNode(
+ *      WithJWTAccessToken("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."),
+ *      WithServerUrl("https://api.example.com")
+ *    );
+ *    ```
+ *
+ * 4. **JWT with Group Context** (user session with specific group):
+ *    ```typescript
+ *    const client = new ServiceNode(
+ *      WithJWTAccessToken("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."),
+ *      WithGroup("groups/01ARZ3NDEKTSV4YWVF8F5BH32"),
+ *      WithServerUrl("https://api.example.com")
+ *    );
+ *    ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClientConfig = void 0;
+exports.WithAPIKey = WithAPIKey;
+exports.WithJWTAccessToken = WithJWTAccessToken;
+exports.WithGroup = WithGroup;
+exports.WithServerUrl = WithServerUrl;
+exports.buildConfigFromOptions = buildConfigFromOptions;
+/**
+ * Internal configuration class used to build client configuration.
+ */
+class ClientConfig {
+    constructor() {
+        /** API server URL (default: production) */
+        this.apiServerURL = "http://localhost:10000";
+    }
+    /**
+     * Validates the configuration.
+     * @throws {Error} If both API key and JWT token are provided (mutually exclusive)
+     */
+    validate() {
+        if (this.apiKey && this.jwtToken) {
+            throw new Error("API key and JWT token authentication are mutually exclusive. " +
+                "Please use WithAPIKey() OR WithJWTAccessToken(), not both.");
+        }
+    }
+}
+exports.ClientConfig = ClientConfig;
+/**
+ * Configures the client with an API key for service-to-service authentication.
+ *
+ * **Mutually Exclusive**: Cannot be used with WithJWTAccessToken().
+ * **Optional**: Can be combined with WithGroup() for group-specific operations.
+ *
+ * @param apiKey - The API key for authentication
+ * @returns A client option function
+ *
+ * @example
+ * ```typescript
+ * const client = new ServiceNode(
+ *   WithAPIKey("your-api-key"),
+ *   WithGroup("groups/01ARZ3NDEKTSV4YWVF8F5BH32")
+ * );
+ * ```
+ */
+function WithAPIKey(apiKey) {
+    return (config) => {
+        if (!apiKey || apiKey.trim() === "") {
+            throw new Error("API key cannot be empty");
+        }
+        if (config.jwtToken) {
+            throw new Error("Cannot use both WithAPIKey() and WithJWTAccessToken(). " +
+                "Please choose one authentication method.");
+        }
+        config.apiKey = apiKey;
+    };
+}
+/**
+ * Configures the client with a JWT access token for user session authentication.
+ *
+ * **Mutually Exclusive**: Cannot be used with WithAPIKey().
+ * **Optional**: Can be combined with WithGroup() for group-specific operations.
+ *
+ * The JWT is injected as a cookie header (Cookie: AccessToken=<jwt>)
+ * so the server can extract it from the request.
+ *
+ * @param token - The JWT access token from the user's session
+ * @returns A client option function
+ *
+ * @example
+ * ```typescript
+ * const client = new ServiceNode(
+ *   WithJWTAccessToken("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."),
+ *   WithGroup("groups/01ARZ3NDEKTSV4YWVF8F5BH32")
+ * );
+ * ```
+ */
+function WithJWTAccessToken(token) {
+    return (config) => {
+        if (!token || token.trim() === "") {
+            throw new Error("JWT token cannot be empty");
+        }
+        if (config.apiKey) {
+            throw new Error("Cannot use both WithJWTAccessToken() and WithAPIKey(). " +
+                "Please choose one authentication method.");
+        }
+        config.jwtToken = token;
+    };
+}
+/**
+ * Configures the client with a group context for operations.
+ *
+ * **Optional**: Can be used with WithAPIKey() or WithJWTAccessToken().
+ * When used alone without authentication, adds group header to requests.
+ *
+ * @param group - The group resource name in format "groups/{ulid}"
+ * @returns A client option function
+ *
+ * @example
+ * ```typescript
+ * // With API Key
+ * const client = new ServiceNode(
+ *   WithAPIKey("your-api-key"),
+ *   WithGroup("groups/01ARZ3NDEKTSV4YWVF8F5BH32")
+ * );
+ *
+ * // With JWT
+ * const client = new ServiceNode(
+ *   WithJWTAccessToken("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."),
+ *   WithGroup("groups/01ARZ3NDEKTSV4YWVF8F5BH32")
+ * );
+ * ```
+ */
+function WithGroup(group) {
+    return (config) => {
+        if (!group || group.trim() === "") {
+            throw new Error("Group cannot be empty");
+        }
+        config.group = group;
+    };
+}
+/**
+ * Configures the client with a custom server URL.
+ *
+ * **Optional**: If not provided, defaults to localhost:10000.
+ *
+ * @param url - The API server URL
+ * @returns A client option function
+ *
+ * @example
+ * ```typescript
+ * const client = new ServiceNode(
+ *   WithServerUrl("http://localhost:10000"),
+ *   WithAPIKey("your-api-key"),
+ *   WithGroup("groups/01ARZ3NDEKTSV4YWVF8F5BH32")
+ * );
+ * ```
+ */
+function WithServerUrl(url) {
+    return (config) => {
+        if (!url || url.trim() === "") {
+            throw new Error("Server URL cannot be empty");
+        }
+        config.apiServerURL = url;
+    };
+}
+/**
+ * Builds client configuration from an array of option functions.
+ *
+ * @param opts - Variable number of option functions
+ * @returns A validated ClientConfig instance
+ * @throws {Error} If configuration is invalid (e.g., both API key and JWT provided)
+ *
+ * @example
+ * ```typescript
+ * const config = buildConfigFromOptions(
+ *   WithAPIKey("your-api-key"),
+ *   WithGroup("groups/01ARZ3NDEKTSV4YWVF8F5BH32"),
+ *   WithServerUrl("https://api.example.com")
+ * );
+ * ```
+ */
+function buildConfigFromOptions(...opts) {
+    const config = new ClientConfig();
+    // Apply each option
+    for (const opt of opts) {
+        opt(config);
+    }
+    // Validate the final configuration
+    config.validate();
+    return config;
+}

package/dist/meshtrade/iam/api_user/v1/api_user_pb.d.ts

@@ -34,12 +34,20 @@ export type APIUser = Message<"meshtrade.iam.api_user.v1.APIUser"> & {
      * @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[];
     /**
      *
      * A non-unique, user-provided name for the API user, used for display purposes.
      * Required on creation.
      *
-     * @generated from field: string display_name = 3;
+     * @generated from field: string display_name = 4;
      */
     displayName: string;
     /**
@@ -47,7 +55,7 @@ export type APIUser = Message<"meshtrade.iam.api_user.v1.APIUser"> & {
      * The current state of the API user (active or inactive).
      * System set on creation to default value of inactive.
      *
-     * @generated from field: meshtrade.iam.api_user.v1.APIUserState state = 4;
+     * @generated from field: meshtrade.iam.api_user.v1.APIUserState state = 5;
      */
     state: APIUserState;
     /**
@@ -56,7 +64,7 @@ export type APIUser = Message<"meshtrade.iam.api_user.v1.APIUser"> & {
      * 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 = 5;
+     * @generated from field: repeated string roles = 6;
      */
     roles: string[];
     /**
@@ -65,7 +73,7 @@ export type APIUser = Message<"meshtrade.iam.api_user.v1.APIUser"> & {
      * This field is only populated on the entity the first time it is returned after creation - it is NOT stored.
      * Populated once by system on creation.
      *
-     * @generated from field: string api_key = 6;
+     * @generated from field: string api_key = 7;
      */
     apiKey: string;
 };

package/dist/meshtrade/iam/api_user/v1/api_user_pb.js

@@ -9,7 +9,7 @@ const validate_pb_1 = require("../../../../buf/validate/validate_pb");
 /**
  * Describes the file meshtrade/iam/api_user/v1/api_user.proto.
  */
-exports.file_meshtrade_iam_api_user_v1_api_user = (0, codegenv2_1.fileDesc)("CihtZXNodHJhZGUvaWFtL2FwaV91c2VyL3YxL2FwaV91c2VyLnByb3RvEhltZXNodHJhZGUuaWFtLmFwaV91c2VyLnYxIvAFCgdBUElVc2VyErwBCgRuYW1lGAEgASgJQq0BukipAboBpQEKFG5hbWUuZm9ybWF0Lm9wdGlvbmFsEjZuYW1lIG11c3QgYmUgZW1wdHkgb3IgaW4gdGhlIGZvcm1hdCBhcGlfdXNlcnMve1VMSUR2Mn0aVXNpemUodGhpcykgPT0gMCB8fCB0aGlzLm1hdGNoZXMoJ15hcGlfdXNlcnMvWzAxMjM0NTY3ODlBQkNERUZHSEpLTU5QUVJTVFZXWFlaXXsyNn0kJykSSwoFb3duZXIYAiABKAlCPLpIOcgBAXI0Mi9eZ3JvdXBzL1swMTIzNDU2Nzg5QUJDREVGR0hKS01OUFFSU1RWV1hZWl17MjZ9JJgBIRKnAQoMZGlzcGxheV9uYW1lGAMgASgJQpABukiMAboBfwoVZGlzcGxheV9uYW1lLnJlcXVpcmVkEkFkaXNwbGF5IG5hbWUgaXMgcmVxdWlyZWQgYW5kIG11c3QgYmUgYmV0d2VlbiAxIGFuZCAyNTUgY2hhcmFjdGVycxojc2l6ZSh0aGlzKSA+IDAgJiYgc2l6ZSh0aGlzKSA8PSAyNTXIAQFyBRABGP8BErcBCgVzdGF0ZRgEIAEoDjInLm1lc2h0cmFkZS5pYW0uYXBpX3VzZXIudjEuQVBJVXNlclN0YXRlQn+6SHy6AXQKC3N0YXRlLnZhbGlkEi9zdGF0ZSBtdXN0IGJlIGEgdmFsaWQgQVBJVXNlclN0YXRlIGlmIHNwZWNpZmllZBo0aW50KHRoaXMpID09IDAgfHwgKGludCh0aGlzKSA+PSAxICYmIGludCh0aGlzKSA8PSAyKYIBAhABEmQKBXJvbGVzGAUgAygJQlW6SFKSAU8iTXJLEC8YMDJFXmdyb3Vwcy9bMDEyMzQ1Njc4OUFCQ0RFRkdISktNTlBRUlNUVldYWVpdezI2fS9yb2xlcy9bMS05XVswLTldezYsN30kEg8KB2FwaV9rZXkYBiABKAkqZgoMQVBJVXNlclN0YXRlEh4KGkFQSV9VU0VSX1NUQVRFX1VOU1BFQ0lGSUVEEAASGQoVQVBJX1VTRVJfU1RBVEVfQUNUSVZFEAESGwoXQVBJX1VTRVJfU1RBVEVfSU5BQ1RJVkUQAiqmAQoNQVBJVXNlckFjdGlvbhIfChtBUElfVVNFUl9BQ1RJT05fVU5TUEVDSUZJRUQQABIcChhBUElfVVNFUl9BQ1RJT05fQUNUSVZBVEUQARIeChpBUElfVVNFUl9BQ1RJT05fREVBQ1RJVkFURRACEhoKFkFQSV9VU0VSX0FDVElPTl9DUkVBVEUQAxIaChZBUElfVVNFUl9BQ1RJT05fVVBEQVRFEARCWwogY28ubWVzaHRyYWRlLmFwaS5pYW0uYXBpX3VzZXIudjFaN2dpdGh1Yi5jb20vbWVzaHRyYWRlL2FwaS9nby9pYW0vYXBpX3VzZXIvdjE7YXBpX3VzZXJfdjFiBnByb3RvMw", [validate_pb_1.file_buf_validate_validate]);
+exports.file_meshtrade_iam_api_user_v1_api_user = (0, codegenv2_1.fileDesc)("CihtZXNodHJhZGUvaWFtL2FwaV91c2VyL3YxL2FwaV91c2VyLnByb3RvEhltZXNodHJhZGUuaWFtLmFwaV91c2VyLnYxIsAGCgdBUElVc2VyErwBCgRuYW1lGAEgASgJQq0BukipAboBpQEKFG5hbWUuZm9ybWF0Lm9wdGlvbmFsEjZuYW1lIG11c3QgYmUgZW1wdHkgb3IgaW4gdGhlIGZvcm1hdCBhcGlfdXNlcnMve1VMSUR2Mn0aVXNpemUodGhpcykgPT0gMCB8fCB0aGlzLm1hdGNoZXMoJ15hcGlfdXNlcnMvWzAxMjM0NTY3ODlBQkNERUZHSEpLTU5QUVJTVFZXWFlaXXsyNn0kJykSSwoFb3duZXIYAiABKAlCPLpIOcgBAXI0Mi9eZ3JvdXBzL1swMTIzNDU2Nzg5QUJDREVGR0hKS01OUFFSU1RWV1hZWl17MjZ9JJgBIRJOCgZvd25lcnMYAyADKAlCPrpIO5IBOCI2cjQyL15ncm91cHMvWzAxMjM0NTY3ODlBQkNERUZHSEpLTU5QUVJTVFZXWFlaXXsyNn0kmAEhEqcBCgxkaXNwbGF5X25hbWUYBCABKAlCkAG6SIwBugF/ChVkaXNwbGF5X25hbWUucmVxdWlyZWQSQWRpc3BsYXkgbmFtZSBpcyByZXF1aXJlZCBhbmQgbXVzdCBiZSBiZXR3ZWVuIDEgYW5kIDI1NSBjaGFyYWN0ZXJzGiNzaXplKHRoaXMpID4gMCAmJiBzaXplKHRoaXMpIDw9IDI1NcgBAXIFEAEY/wEStwEKBXN0YXRlGAUgASgOMicubWVzaHRyYWRlLmlhbS5hcGlfdXNlci52MS5BUElVc2VyU3RhdGVCf7pIfLoBdAoLc3RhdGUudmFsaWQSL3N0YXRlIG11c3QgYmUgYSB2YWxpZCBBUElVc2VyU3RhdGUgaWYgc3BlY2lmaWVkGjRpbnQodGhpcykgPT0gMCB8fCAoaW50KHRoaXMpID49IDEgJiYgaW50KHRoaXMpIDw9IDIpggECEAESZAoFcm9sZXMYBiADKAlCVbpIUpIBTyJNcksQLxgwMkVeZ3JvdXBzL1swMTIzNDU2Nzg5QUJDREVGR0hKS01OUFFSU1RWV1hZWl17MjZ9L3JvbGVzL1sxLTldWzAtOV17Niw3fSQSDwoHYXBpX2tleRgHIAEoCSpmCgxBUElVc2VyU3RhdGUSHgoaQVBJX1VTRVJfU1RBVEVfVU5TUEVDSUZJRUQQABIZChVBUElfVVNFUl9TVEFURV9BQ1RJVkUQARIbChdBUElfVVNFUl9TVEFURV9JTkFDVElWRRACKqYBCg1BUElVc2VyQWN0aW9uEh8KG0FQSV9VU0VSX0FDVElPTl9VTlNQRUNJRklFRBAAEhwKGEFQSV9VU0VSX0FDVElPTl9BQ1RJVkFURRABEh4KGkFQSV9VU0VSX0FDVElPTl9ERUFDVElWQVRFEAISGgoWQVBJX1VTRVJfQUNUSU9OX0NSRUFURRADEhoKFkFQSV9VU0VSX0FDVElPTl9VUERBVEUQBEJuCiBjby5tZXNodHJhZGUuYXBpLmlhbS5hcGlfdXNlci52MUIRQXBpVXNlck91dGVyQ2xhc3NaN2dpdGh1Yi5jb20vbWVzaHRyYWRlL2FwaS9nby9pYW0vYXBpX3VzZXIvdjE7YXBpX3VzZXJfdjFiBnByb3RvMw", [validate_pb_1.file_buf_validate_validate]);
 /**
  * Describes the message meshtrade.iam.api_user.v1.APIUser.
  * Use `create(APIUserSchema)` to create a new message.

package/dist/meshtrade/iam/api_user/v1/service_node_meshts.d.ts

@@ -1,59 +1,84 @@
-import { Interceptor } from "@connectrpc/connect";
 import { ActivateAPIUserRequest, AssignRolesToAPIUserRequest, CreateAPIUserRequest, DeactivateAPIUserRequest, GetAPIUserByKeyHashRequest, GetAPIUserRequest, ListAPIUsersRequest, ListAPIUsersResponse, RevokeRolesFromAPIUserRequest, SearchAPIUsersRequest, SearchAPIUsersResponse } from "./service_pb";
 import { APIUser } from "./api_user_pb";
-import { ConfigOpts } from "../../../common/config";
+import { ClientOption } from "../../../config";
 /**
  * Node.js client for interacting with the meshtrade.iam.api_user.v1 apiuser v1 API resource service.
  * Uses Connect-ES with gRPC transport for Node.js gRPC communication.
  *
- * Supports three authentication modes:
+ * Supports flexible authentication modes using functional options pattern:
  *
  * 1. **No Authentication** (public APIs):
  *    ```typescript
- *    const client = new APIUserServiceNode({ apiServerURL: "http://localhost:10000" });
+ *    const client = new APIUserServiceNode(
+ *      WithServerUrl("http://localhost:10000")
+ *    );
  *    ```
  *
  * 2. **API Key Authentication** (backend services):
  *    ```typescript
- *    const client = new APIUserServiceNode({
- *      apiServerURL: "https://api.example.com",
- *      apiKey: "your-api-key",
- *      group: "groups/01ARZ3NDEKTSV4YWVF8F5BH32"
- *    });
+ *    const client = new APIUserServiceNode(
+ *      WithAPIKey("your-api-key"),
+ *      WithGroup("groups/01ARZ3NDEKTSV4YWVF8F5BH32"),
+ *      WithServerUrl("https://api.example.com")
+ *    );
  *    ```
  *
  * 3. **JWT Token Authentication** (Next.js backend with user session):
  *    ```typescript
- *    const client = new APIUserServiceNode({
- *      apiServerURL: "https://api.example.com",
- *      jwtToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
- *    });
+ *    const client = new APIUserServiceNode(
+ *      WithJWTAccessToken("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."),
+ *      WithServerUrl("https://api.example.com")
+ *    );
  *    ```
+ *
+ * 4. **JWT with Group Context** (user session with specific group):
+ *    ```typescript
+ *    const client = new APIUserServiceNode(
+ *      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 APIUserServiceNode {
     private _client;
     private readonly _config;
     private readonly _interceptors;
+    private readonly _validator;
     /**
      * Constructs an instance of APIUserServiceNode.
-     * @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.
      *
-     * **Important**: This method only works with API key authentication.
-     * - For **API key auth**: Creates a new client with updated group context
-     * - For **JWT auth**: Throws error (group comes from JWT token claims)
-     * - For **no auth**: Throws error (group requires authentication)
+     * 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 {APIUserServiceNode} A new, configured instance of the client.
-     * @throws {Error} If used with JWT authentication or no authentication
      * @throws {Error} If the group format is invalid
      */
     withGroup(group: string): APIUserServiceNode;