@meshtrade/api-web 1.30.0

package/dist/meshtrade/common/connectInterceptors.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Connect-ES interceptors for the Meshtrade API client (Web/Browser).
+ *
+ * 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.
+ */
+import { Interceptor } from "@connectrpc/connect";
+/**
+ * Creates a Connect-ES interceptor that injects operating group context
+ * into API requests by adding an `x-group` header.
+ *
+ * The group context determines the scope of operations and resource access
+ * within the Meshtrade platform's hierarchical group ownership model.
+ *
+ * This interceptor validates that the provided group follows the correct
+ * resource name format: `groups/{ulid}` where {ulid} is a 26-character
+ * ULID (Universally Unique Lexicographically Sortable Identifier).
+ *
+ * @param group - The group resource name in the format `groups/{ulid}` where
+ *                {ulid} is a 26-character ULID identifier. This determines
+ *                the operating group context for all API requests.
+ * @returns An interceptor function that adds the group header to all requests
+ * @throws {Error} If the group format is invalid
+ *
+ * @example
+ * ```typescript
+ * // Create an interceptor with a valid group resource name
+ * const groupInterceptor = createGroupInterceptor('groups/01ARZ3NDEKTSV4YWVF8F5BH32');
+ *
+ * // Use with a Connect-ES client
+ * const transport = createGrpcWebTransport({
+ *   baseUrl: 'https://api.example.com',
+ *   interceptors: [groupInterceptor]
+ * });
+ *
+ * const client = createPromiseClient(MyService, transport);
+ * ```
+ */
+export declare function createGroupInterceptor(group: string): Interceptor & {
+    groupContext: string;
+};
+/**
+ * Creates a logging interceptor that logs all requests and responses.
+ * Useful for debugging and development.
+ *
+ * @returns An interceptor function that logs request/response details
+ *
+ * @example
+ * ```typescript
+ * const loggingInterceptor = createLoggingInterceptor();
+ *
+ * const transport = createGrpcWebTransport({
+ *   baseUrl: 'https://api.example.com',
+ *   interceptors: [loggingInterceptor]
+ * });
+ * ```
+ */
+export declare function createLoggingInterceptor(): Interceptor;

package/dist/meshtrade/common/connectInterceptors.js

@@ -0,0 +1,126 @@
+"use strict";
+/**
+ * Connect-ES interceptors for the Meshtrade API client (Web/Browser).
+ *
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createGroupInterceptor = createGroupInterceptor;
+exports.createLoggingInterceptor = createLoggingInterceptor;
+const validation_1 = require("./validation");
+/**
+ * Creates a Connect-ES interceptor that injects operating group context
+ * into API requests by adding an `x-group` header.
+ *
+ * The group context determines the scope of operations and resource access
+ * within the Meshtrade platform's hierarchical group ownership model.
+ *
+ * This interceptor validates that the provided group follows the correct
+ * resource name format: `groups/{ulid}` where {ulid} is a 26-character
+ * ULID (Universally Unique Lexicographically Sortable Identifier).
+ *
+ * @param group - The group resource name in the format `groups/{ulid}` where
+ *                {ulid} is a 26-character ULID identifier. This determines
+ *                the operating group context for all API requests.
+ * @returns An interceptor function that adds the group header to all requests
+ * @throws {Error} If the group format is invalid
+ *
+ * @example
+ * ```typescript
+ * // Create an interceptor with a valid group resource name
+ * const groupInterceptor = createGroupInterceptor('groups/01ARZ3NDEKTSV4YWVF8F5BH32');
+ *
+ * // Use with a Connect-ES client
+ * const transport = createGrpcWebTransport({
+ *   baseUrl: 'https://api.example.com',
+ *   interceptors: [groupInterceptor]
+ * });
+ *
+ * const client = createPromiseClient(MyService, transport);
+ * ```
+ */
+function createGroupInterceptor(group) {
+    // Validate the group resource name format
+    if (!(0, validation_1.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
+        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 logging interceptor that logs all requests and responses.
+ * Useful for debugging and development.
+ *
+ * @returns An interceptor function that logs request/response details
+ *
+ * @example
+ * ```typescript
+ * const loggingInterceptor = createLoggingInterceptor();
+ *
+ * const transport = createGrpcWebTransport({
+ *   baseUrl: 'https://api.example.com',
+ *   interceptors: [loggingInterceptor]
+ * });
+ * ```
+ */
+function createLoggingInterceptor() {
+    return (next) => async (req) => {
+        // Convert headers to plain object for logging
+        const headers = {};
+        req.header.forEach((value, key) => {
+            headers[key] = value;
+        });
+        // Log the request
+        console.log(`[Connect] ${req.method.name} request:`, {
+            service: req.service.typeName,
+            method: req.method.name,
+            headers,
+        });
+        try {
+            // Call the next interceptor and get the response
+            const response = await next(req);
+            // Log successful response
+            console.log(`[Connect] ${req.method.name} response:`, {
+                service: req.service.typeName,
+                method: req.method.name,
+                status: "success",
+            });
+            return response;
+        }
+        catch (error) {
+            // Log error
+            console.error(`[Connect] ${req.method.name} error:`, {
+                service: req.service.typeName,
+                method: req.method.name,
+                error: error,
+            });
+            // Re-throw the error
+            throw error;
+        }
+    };
+}

package/dist/meshtrade/common/validation.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Generic validation utilities for Meshtrade API resource names and identifiers.
+ */
+/**
+ * Validates if a string is a valid ULID (Universally Unique Lexicographically Sortable Identifier).
+ *
+ * Note: This implementation uses a simplified character set for ULIDs that includes
+ * all uppercase letters A-Z and digits 0-9, unlike the standard ULID specification
+ * which excludes certain ambiguous characters (I, L, O, U).
+ *
+ * ULIDs in this system are 26-character identifiers that are:
+ * - Lexicographically sortable
+ * - Uppercase alphanumeric only
+ * - Contain timestamp information for natural ordering
+ *
+ * @param ulid - The string to validate as a ULID
+ * @returns true if the string is a valid ULID format, false otherwise
+ *
+ * @example
+ * ```typescript
+ * isValidULID('01ARZ3NDEKTSV4YWVF8F5BH32'); // true
+ * isValidULID('invalid'); // false
+ * isValidULID('01arz3ndektsv4ywvf8f5bh32'); // false (lowercase)
+ * ```
+ */
+export declare function isValidULID(ulid: string): boolean;
+/**
+ * Validates if a resource name follows the groups/{ulid} format.
+ *
+ * Group resource names in the Meshtrade API follow the pattern "groups/{ulid}"
+ * where {ulid} is a 26-character ULID identifier.
+ *
+ * @param resourceName - The resource name string to validate
+ * @returns true if the resource name is a valid group resource name, false otherwise
+ *
+ * @example
+ * ```typescript
+ * isValidGroupResourceName('groups/01ARZ3NDEKTSV4YWVF8F5BH32'); // true
+ * isValidGroupResourceName('groups/invalid'); // false
+ * isValidGroupResourceName('users/01ARZ3NDEKTSV4YWVF8F5BH32'); // false
+ * isValidGroupResourceName('01ARZ3NDEKTSV4YWVF8F5BH32'); // false
+ * ```
+ */
+export declare function isValidGroupResourceName(resourceName: string): boolean;
+/**
+ * Validates a protobuf request message before sending to the server.
+ *
+ * This function serves as a client-side validation hook that can be extended
+ * to include protovalidate integration or other validation logic.
+ *
+ * Currently performs basic null/undefined checks. Future enhancements may include
+ * protovalidate integration for comprehensive message validation.
+ *
+ * @param request - The protobuf request message to validate
+ * @throws {Error} If the request is null or undefined
+ *
+ * @example
+ * ```typescript
+ * validateRequest(myRequest); // Throws if request is invalid
+ * ```
+ */
+export declare function validateRequest(request: unknown): void;

package/dist/meshtrade/common/validation.js

@@ -0,0 +1,77 @@
+"use strict";
+/**
+ * Generic validation utilities for Meshtrade API resource names and identifiers.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidULID = isValidULID;
+exports.isValidGroupResourceName = isValidGroupResourceName;
+exports.validateRequest = validateRequest;
+/**
+ * Validates if a string is a valid ULID (Universally Unique Lexicographically Sortable Identifier).
+ *
+ * Note: This implementation uses a simplified character set for ULIDs that includes
+ * all uppercase letters A-Z and digits 0-9, unlike the standard ULID specification
+ * which excludes certain ambiguous characters (I, L, O, U).
+ *
+ * ULIDs in this system are 26-character identifiers that are:
+ * - Lexicographically sortable
+ * - Uppercase alphanumeric only
+ * - Contain timestamp information for natural ordering
+ *
+ * @param ulid - The string to validate as a ULID
+ * @returns true if the string is a valid ULID format, false otherwise
+ *
+ * @example
+ * ```typescript
+ * isValidULID('01ARZ3NDEKTSV4YWVF8F5BH32'); // true
+ * isValidULID('invalid'); // false
+ * isValidULID('01arz3ndektsv4ywvf8f5bh32'); // false (lowercase)
+ * ```
+ */
+function isValidULID(ulid) {
+    return /^[0-9A-Z]{26}$/.test(ulid);
+}
+/**
+ * Validates if a resource name follows the groups/{ulid} format.
+ *
+ * Group resource names in the Meshtrade API follow the pattern "groups/{ulid}"
+ * where {ulid} is a 26-character ULID identifier.
+ *
+ * @param resourceName - The resource name string to validate
+ * @returns true if the resource name is a valid group resource name, false otherwise
+ *
+ * @example
+ * ```typescript
+ * isValidGroupResourceName('groups/01ARZ3NDEKTSV4YWVF8F5BH32'); // true
+ * isValidGroupResourceName('groups/invalid'); // false
+ * isValidGroupResourceName('users/01ARZ3NDEKTSV4YWVF8F5BH32'); // false
+ * isValidGroupResourceName('01ARZ3NDEKTSV4YWVF8F5BH32'); // false
+ * ```
+ */
+function isValidGroupResourceName(resourceName) {
+    return /^groups\/[0-9A-Z]{26}$/.test(resourceName);
+}
+/**
+ * Validates a protobuf request message before sending to the server.
+ *
+ * This function serves as a client-side validation hook that can be extended
+ * to include protovalidate integration or other validation logic.
+ *
+ * Currently performs basic null/undefined checks. Future enhancements may include
+ * protovalidate integration for comprehensive message validation.
+ *
+ * @param request - The protobuf request message to validate
+ * @throws {Error} If the request is null or undefined
+ *
+ * @example
+ * ```typescript
+ * validateRequest(myRequest); // Throws if request is invalid
+ * ```
+ */
+function validateRequest(request) {
+    if (request === null || request === undefined) {
+        throw new Error("Request cannot be null or undefined");
+    }
+    // Future: Integrate protovalidate for comprehensive message validation
+    // For now, basic validation is sufficient as the server also validates
+}

package/dist/meshtrade/compliance/client/v1/client_pb.d.ts

@@ -0,0 +1,138 @@
+import type { GenFile, GenMessage } from "@bufbuild/protobuf/codegenv2";
+import type { Timestamp } from "@bufbuild/protobuf/wkt";
+import type { Company } from "./company_pb";
+import type { Fund } from "./fund_pb";
+import type { NaturalPerson } from "./natural_person_pb";
+import type { Trust } from "./trust_pb";
+import type { VerificationStatus } from "./verification_status_pb";
+import type { Message } from "@bufbuild/protobuf";
+/**
+ * Describes the file meshtrade/compliance/client/v1/client.proto.
+ */
+export declare const file_meshtrade_compliance_client_v1_client: GenFile;
+/**
+ *
+ * Client represents an authorized legal entity, which can be either an individual (KYC)
+ * or a business (KYB). It serves as the central resource for all compliance information
+ * and verification status related to a single party.
+ *
+ * @generated from message meshtrade.compliance.client.v1.Client
+ */
+export type Client = Message<"meshtrade.compliance.client.v1.Client"> & {
+    /**
+     *
+     * The unique, immutable, and canonical name of the client resource in the format clients/{client_id}.
+     * The {client_id} is a system-generated unique identifier (e.g., UUID) that will never change. This name field will never change and should be used as the permanent primary key for this resource in all systems.
+     * System set on creation.
+     *
+     * @generated from field: string name = 1;
+     */
+    name: string;
+    /**
+     *
+     * The resource name of the group that owns this client in the format groups/{group_id}.
+     * This field establishes the ownership link and can be updated if the client's ownership changes,
+     * without affecting the client's stable `name`.
+     * The executing user needs to have permission to perform client.Create in this group.
+     * Required on creation.
+     *
+     * @generated from field: string owner = 2;
+     */
+    owner: string;
+    /**
+     *
+     * A non-unique, user-provided name for the client, used for display purposes
+     * in user interfaces and reports.
+     * Required on creation.
+     *
+     * @generated from field: string display_name = 3;
+     */
+    displayName: string;
+    /**
+     *
+     * Contains the specific data for the legal entity type.
+     * Only one of these may be set at a time.
+     *
+     * @generated from oneof meshtrade.compliance.client.v1.Client.legal_person
+     */
+    legalPerson: {
+        /**
+         *
+         * Set when the legal entity is an individual human being.
+         *
+         * @generated from field: meshtrade.compliance.client.v1.NaturalPerson natural_person = 4;
+         */
+        value: NaturalPerson;
+        case: "naturalPerson";
+    } | {
+        /**
+         *
+         * Set when the legal entity is a company or corporation.
+         *
+         * @generated from field: meshtrade.compliance.client.v1.Company company = 5;
+         */
+        value: Company;
+        case: "company";
+    } | {
+        /**
+         *
+         * Set when the legal entity is an investment fund.
+         *
+         * @generated from field: meshtrade.compliance.client.v1.Fund fund = 6;
+         */
+        value: Fund;
+        case: "fund";
+    } | {
+        /**
+         *
+         * Set when the legal entity is a trust.
+         *
+         * @generated from field: meshtrade.compliance.client.v1.Trust trust = 7;
+         */
+        value: Trust;
+        case: "trust";
+    } | {
+        case: undefined;
+        value?: undefined;
+    };
+    /**
+     *
+     * The definitive, most recent compliance status of the client (e.g., VERIFICATION_STATUS_VERIFIED, VERIFICATION_STATUS_FAILED).
+     * Must always be a valid field
+     *
+     * @generated from field: meshtrade.compliance.client.v1.VerificationStatus verification_status = 8;
+     */
+    verificationStatus: VerificationStatus;
+    /**
+     *
+     * The resource name of the client (acting as a verifier) that last set the
+     * `verification_status`. This provides an audit trail for status changes.
+     * System set when verification_status changes.
+     *
+     * @generated from field: string verification_authority = 9;
+     */
+    verificationAuthority: string;
+    /**
+     *
+     * The timestamp when the `verification_status` was last set to a conclusive
+     * state, specifically `VERIFICATION_STATUS_VERIFIED`.
+     * System set when verification_status changes to VERIFICATION_STATUS_VERIFIED.
+     *
+     * @generated from field: google.protobuf.Timestamp verification_date = 10;
+     */
+    verificationDate?: Timestamp;
+    /**
+     *
+     * The timestamp indicating when the client's next periodic compliance review
+     * is due. This field drives re-verification workflows.
+     * Optional for Verification.
+     *
+     * @generated from field: google.protobuf.Timestamp next_verification_date = 11;
+     */
+    nextVerificationDate?: Timestamp;
+};
+/**
+ * Describes the message meshtrade.compliance.client.v1.Client.
+ * Use `create(ClientSchema)` to create a new message.
+ */
+export declare const ClientSchema: GenMessage<Client>;

package/dist/meshtrade/compliance/client/v1/client_pb.js

@@ -0,0 +1,23 @@
+"use strict";
+// @generated by protoc-gen-es v2.10.1 with parameter "target=ts"
+// @generated from file meshtrade/compliance/client/v1/client.proto (package meshtrade.compliance.client.v1, syntax proto3)
+/* eslint-disable */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClientSchema = exports.file_meshtrade_compliance_client_v1_client = void 0;
+const codegenv2_1 = require("@bufbuild/protobuf/codegenv2");
+const validate_pb_1 = require("../../../../buf/validate/validate_pb");
+const wkt_1 = require("@bufbuild/protobuf/wkt");
+const company_pb_1 = require("./company_pb");
+const fund_pb_1 = require("./fund_pb");
+const natural_person_pb_1 = require("./natural_person_pb");
+const trust_pb_1 = require("./trust_pb");
+const verification_status_pb_1 = require("./verification_status_pb");
+/**
+ * Describes the file meshtrade/compliance/client/v1/client.proto.
+ */
+exports.file_meshtrade_compliance_client_v1_client = (0, codegenv2_1.fileDesc)("CittZXNodHJhZGUvY29tcGxpYW5jZS9jbGllbnQvdjEvY2xpZW50LnByb3RvEh5tZXNodHJhZGUuY29tcGxpYW5jZS5jbGllbnQudjEi+gcKBkNsaWVudBK4AQoEbmFtZRgBIAEoCUKpAbpIpQG6AaEBChRuYW1lLmZvcm1hdC5vcHRpb25hbBI0bmFtZSBtdXN0IGJlIGVtcHR5IG9yIGluIHRoZSBmb3JtYXQgY2xpZW50cy97VUxJRHYyfRpTc2l6ZSh0aGlzKSA9PSAwIHx8IHRoaXMubWF0Y2hlcygnXmNsaWVudHMvWzAxMjM0NTY3ODlBQkNERUZHSEpLTU5QUVJTVFZXWFlaXXsyNn0kJykSSwoFb3duZXIYAiABKAlCPLpIOcgBAXI0Mi9eZ3JvdXBzL1swMTIzNDU2Nzg5QUJDREVGR0hKS01OUFFSU1RWV1hZWl17MjZ9JJgBIRIjCgxkaXNwbGF5X25hbWUYAyABKAlCDbpICsgBAXIFEAEY/wESRwoObmF0dXJhbF9wZXJzb24YBCABKAsyLS5tZXNodHJhZGUuY29tcGxpYW5jZS5jbGllbnQudjEuTmF0dXJhbFBlcnNvbkgAEjoKB2NvbXBhbnkYBSABKAsyJy5tZXNodHJhZGUuY29tcGxpYW5jZS5jbGllbnQudjEuQ29tcGFueUgAEjQKBGZ1bmQYBiABKAsyJC5tZXNodHJhZGUuY29tcGxpYW5jZS5jbGllbnQudjEuRnVuZEgAEjYKBXRydXN0GAcgASgLMiUubWVzaHRyYWRlLmNvbXBsaWFuY2UuY2xpZW50LnYxLlRydXN0SAASXAoTdmVyaWZpY2F0aW9uX3N0YXR1cxgIIAEoDjIyLm1lc2h0cmFkZS5jb21wbGlhbmNlLmNsaWVudC52MS5WZXJpZmljYXRpb25TdGF0dXNCC7pICMgBAYIBAhABEu4BChZ2ZXJpZmljYXRpb25fYXV0aG9yaXR5GAkgASgJQs0BukjJAboBxQEKJnZlcmlmaWNhdGlvbl9hdXRob3JpdHkuZm9ybWF0Lm9wdGlvbmFsEkZ2ZXJpZmljYXRpb25fYXV0aG9yaXR5IG11c3QgYmUgZW1wdHkgb3IgaW4gdGhlIGZvcm1hdCBjbGllbnRzL3tVTElEdjJ9GlNzaXplKHRoaXMpID09IDAgfHwgdGhpcy5tYXRjaGVzKCdeY2xpZW50cy9bMDEyMzQ1Njc4OUFCQ0RFRkdISktNTlBRUlNUVldYWVpdezI2fSQnKRI1ChF2ZXJpZmljYXRpb25fZGF0ZRgKIAEoCzIaLmdvb2dsZS5wcm90b2J1Zi5UaW1lc3RhbXASOgoWbmV4dF92ZXJpZmljYXRpb25fZGF0ZRgLIAEoCzIaLmdvb2dsZS5wcm90b2J1Zi5UaW1lc3RhbXBCDgoMbGVnYWxfcGVyc29uQmMKJWNvLm1lc2h0cmFkZS5hcGkuY29tcGxpYW5jZS5jbGllbnQudjFaOmdpdGh1Yi5jb20vbWVzaHRyYWRlL2FwaS9nby9jb21wbGlhbmNlL2NsaWVudC92MTtjbGllbnRfdjFiBnByb3RvMw", [validate_pb_1.file_buf_validate_validate, wkt_1.file_google_protobuf_timestamp, company_pb_1.file_meshtrade_compliance_client_v1_company, fund_pb_1.file_meshtrade_compliance_client_v1_fund, natural_person_pb_1.file_meshtrade_compliance_client_v1_natural_person, trust_pb_1.file_meshtrade_compliance_client_v1_trust, verification_status_pb_1.file_meshtrade_compliance_client_v1_verification_status]);
+/**
+ * Describes the message meshtrade.compliance.client.v1.Client.
+ * Use `create(ClientSchema)` to create a new message.
+ */
+exports.ClientSchema = (0, codegenv2_1.messageDesc)(exports.file_meshtrade_compliance_client_v1_client, 0);