@vectora/contracts 1.0.0

package/LICENSE.md

@@ -0,0 +1,25 @@
+Copyright (c) 2026 Vectora Inc. All rights reserved.
+
+This software and associated documentation files (the "Software") are the
+exclusive property of Vectora Inc.
+
+The Software is published for the internal use of Vectora Inc. projects and
+is not intended for public use, redistribution, or modification.
+
+PERMISSIONS:
+
+- Use of this Software is strictly limited to authorized employees and
+  systems of Vectora Inc.
+- No part of this Software may be copied, modified, distributed, or
+  sub-licensed to any third party without express written permission
+  from Vectora Inc.
+
+RESTRICTIONS:
+
+- You may not use this Software in any project not owned or managed
+  by Vectora Inc.
+- You may not reverse engineer, decompile, or disassemble the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
+ANY CLAIM, DAMAGES OR OTHER LIABILITY.

package/dist/events/auth/index.d.ts

@@ -0,0 +1 @@
+export * from "./verification-request.interface";

package/dist/events/auth/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./verification-request.interface"), exports);

package/dist/events/auth/verification-request.interface.d.ts

@@ -0,0 +1,5 @@
+export interface verificationRequestEvent {
+    identifier: string;
+    method: "phone" | "email";
+    code: string;
+}

package/dist/events/auth/verification-request.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/events/index.d.ts

@@ -0,0 +1 @@
+export * from "./auth";

package/dist/events/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./auth"), exports);

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./events";
+export * from "./proto";
+export * from "./utils";

package/dist/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./events"), exports);
+__exportStar(require("./proto"), exports);
+__exportStar(require("./utils"), exports);

package/dist/proto/index.d.ts

@@ -0,0 +1 @@
+export * from "./paths";

package/dist/proto/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./paths"), exports);

package/dist/proto/paths.d.ts

@@ -0,0 +1,18 @@
+export declare const PROTO_PATHS: {
+    readonly AUTH: string;
+    readonly ACCOUNT: string;
+    readonly USER: string;
+    readonly COMPANY: string;
+    readonly ROLE: string;
+    readonly SHIPMENTS: string;
+    readonly SHIPMENTS_RATES: string;
+    readonly SHIPMENTS_STOPS: string;
+    readonly SHIPMENTS_FREIGHT: string;
+    readonly FLEET_TRUCKS: string;
+    readonly FLEET_UNITS: string;
+    readonly GEOCODE: string;
+    readonly DIRECTION: string;
+    readonly MATRIX: string;
+    readonly OPTIMIZATION: string;
+    readonly SEARCH: string;
+};

package/dist/proto/paths.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROTO_PATHS = void 0;
+const path_1 = require("path");
+// prettier-ignore
+exports.PROTO_PATHS = {
+    // * Identify
+    AUTH: (0, path_1.join)(__dirname, "../../proto/ts/identify-auth-v1.proto"),
+    ACCOUNT: (0, path_1.join)(__dirname, "../../proto/ts/identify-account-v1.proto"),
+    USER: (0, path_1.join)(__dirname, "../../proto/ts/identify-user-v1.proto"),
+    COMPANY: (0, path_1.join)(__dirname, "../../proto/ts/identify-company-v1.proto"),
+    ROLE: (0, path_1.join)(__dirname, "../../proto/ts/identify-role-v1.proto"),
+    // * shipments
+    SHIPMENTS: (0, path_1.join)(__dirname, "../../proto/ts/shipments-loads-v1.proto"),
+    SHIPMENTS_RATES: (0, path_1.join)(__dirname, "../../proto/ts/shipments-rate-v1.proto"),
+    SHIPMENTS_STOPS: (0, path_1.join)(__dirname, "../../proto/ts/shipments-stop-v1.proto"),
+    SHIPMENTS_FREIGHT: (0, path_1.join)(__dirname, "../../proto/ts/shipments-freight-v1.proto"),
+    // * fleet
+    FLEET_TRUCKS: (0, path_1.join)(__dirname, "../../proto/ts/fleet-truck-v1.proto"),
+    FLEET_UNITS: (0, path_1.join)(__dirname, "../../proto/ts/fleet-unit-v1.proto"),
+    // * geocode
+    GEOCODE: (0, path_1.join)(__dirname, "../../proto/ts/mapbox-geocode-v1.proto"),
+    DIRECTION: (0, path_1.join)(__dirname, "../../proto/ts/mapbox-direction-v1.proto"),
+    MATRIX: (0, path_1.join)(__dirname, "../../proto/ts/mapbox-matrix-v1.proto"),
+    OPTIMIZATION: (0, path_1.join)(__dirname, "../../proto/ts/mapbox-optimization-v1.proto"),
+    SEARCH: (0, path_1.join)(__dirname, "../../proto/ts/mapbox-search-v1.proto"),
+};

package/dist/utils/data-transformer.util.d.ts

@@ -0,0 +1,55 @@
+/**
+ * DataTransformer Utility
+ * * A universal bridge between JS/TypeORM (camelCase) and gRPC (snake_case + FieldMask).
+ * * Features:
+ * - Automatic FieldMask generation (including deep nested paths).
+ * - Auto-detection and unwrapping of Google Protobuf Wrappers (StringValue, Int32Value, etc.).
+ * - Bidirectional conversion between JS Date/ISO-strings and gRPC Timestamps.
+ * - Support for nested objects and repeated fields (arrays).
+ */
+export declare class DataTransformer {
+    /**
+     * Detects if an object is a Google Protobuf Wrapper (e.g., StringValue).
+     */
+    private static isWrapper;
+    /**
+     * Detects if an object is a gRPC Timestamp.
+     */
+    private static isTimestamp;
+    private static toSnakeCase;
+    private static toCamelCase;
+    /**
+     * normalizeRequest
+     * Prepares a JS DTO for gRPC transmission and generates a FieldMask.
+     * * @param dto - Flat or nested JS object (e.g., from an API Controller).
+     * @param prefix - Internal use for recursive path building.
+     * * @example
+     * const { data, updateMask } = DataTransformer.normalizeRequest({
+     * legalName: "Apple",
+     * dbaName: null,
+     * createdAt: "2026-02-12T10:00:00Z",
+     * equipment: [1, 2]
+     * });
+     * * // Result 'data': { legalName: "Apple", dbaName: undefined, createdAt: {seconds: 1770890400...}, equipment: {items: [1,2]} }
+     * // Result 'updateMask': { paths: ["legal_name", "dba_name", "created_at", "equipment"] }
+     */
+    static normalizeRequest<T>(dto: any, prefix?: string): {
+        data: T;
+        updateMask: {
+            paths: string[];
+        };
+    };
+    /**
+     * normalizeResponse
+     * Converts a gRPC response back to a JS/TypeORM Entity format.
+     * * @param source - The gRPC message received.
+     * @param updateMask - The FieldMask for partial updates.
+     * * @example
+     * const entity = DataTransformer.normalizeResponse(grpcResponse, grpcResponse.updateMask);
+     * * // Input: { dbaName: {value: "Test"}, createdAt: {seconds: 1770890400}, equipment: {items: [1]} }
+     * // Output: { dbaName: "Test", createdAt: Date(...), equipment: [1] }
+     */
+    static normalizeResponse<T>(source: any, updateMask?: {
+        paths: string[];
+    }): Partial<T>;
+}

package/dist/utils/data-transformer.util.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DataTransformer = void 0;
+/**
+ * DataTransformer Utility
+ * * A universal bridge between JS/TypeORM (camelCase) and gRPC (snake_case + FieldMask).
+ * * Features:
+ * - Automatic FieldMask generation (including deep nested paths).
+ * - Auto-detection and unwrapping of Google Protobuf Wrappers (StringValue, Int32Value, etc.).
+ * - Bidirectional conversion between JS Date/ISO-strings and gRPC Timestamps.
+ * - Support for nested objects and repeated fields (arrays).
+ */
+class DataTransformer {
+    /**
+     * Detects if an object is a Google Protobuf Wrapper (e.g., StringValue).
+     */
+    static isWrapper(obj) {
+        return (obj !== null &&
+            typeof obj === "object" &&
+            !Array.isArray(obj) &&
+            Object.keys(obj).length === 1 &&
+            "value" in obj);
+    }
+    /**
+     * Detects if an object is a gRPC Timestamp.
+     */
+    static isTimestamp(obj) {
+        return (obj !== null &&
+            typeof obj === "object" &&
+            "seconds" in obj &&
+            typeof obj.seconds === "number");
+    }
+    static toSnakeCase(str) {
+        return str.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+    }
+    static toCamelCase(str) {
+        return str.replace(/(_\w)/g, (m) => m[1].toUpperCase());
+    }
+    /**
+     * normalizeRequest
+     * Prepares a JS DTO for gRPC transmission and generates a FieldMask.
+     * * @param dto - Flat or nested JS object (e.g., from an API Controller).
+     * @param prefix - Internal use for recursive path building.
+     * * @example
+     * const { data, updateMask } = DataTransformer.normalizeRequest({
+     * legalName: "Apple",
+     * dbaName: null,
+     * createdAt: "2026-02-12T10:00:00Z",
+     * equipment: [1, 2]
+     * });
+     * * // Result 'data': { legalName: "Apple", dbaName: undefined, createdAt: {seconds: 1770890400...}, equipment: {items: [1,2]} }
+     * // Result 'updateMask': { paths: ["legal_name", "dba_name", "created_at", "equipment"] }
+     */
+    static normalizeRequest(dto, prefix = "") {
+        const data = {};
+        const paths = [];
+        for (const key in dto) {
+            let value = dto[key];
+            if (value === undefined)
+                continue;
+            const snakeKey = this.toSnakeCase(key);
+            const fullPath = prefix ? `${prefix}.${snakeKey}` : snakeKey;
+            // 1. Date / ISO String detection
+            if (value instanceof Date ||
+                (typeof value === "string" &&
+                    /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:/.test(value))) {
+                const date = value instanceof Date ? value : new Date(value);
+                if (!isNaN(date.getTime())) {
+                    paths.push(fullPath);
+                    data[key] = { seconds: Math.floor(date.getTime() / 1000), nanos: 0 };
+                    continue;
+                }
+            }
+            // 2. Arrays (Repeated fields)
+            if (Array.isArray(value)) {
+                paths.push(fullPath);
+                // Special case for EquipmentInput pattern in your proto
+                data[key] = key === "equipment" ? { items: value } : value;
+            }
+            // 3. Nested Objects
+            else if (value !== null && typeof value === "object") {
+                const nested = this.normalizeRequest(value, fullPath);
+                data[key] = nested.data;
+                paths.push(...nested.updateMask.paths);
+            }
+            // 4. Primitives
+            else {
+                paths.push(fullPath);
+                data[key] = value;
+            }
+        }
+        return { data: data, updateMask: { paths } };
+    }
+    /**
+     * normalizeResponse
+     * Converts a gRPC response back to a JS/TypeORM Entity format.
+     * * @param source - The gRPC message received.
+     * @param updateMask - The FieldMask for partial updates.
+     * * @example
+     * const entity = DataTransformer.normalizeResponse(grpcResponse, grpcResponse.updateMask);
+     * * // Input: { dbaName: {value: "Test"}, createdAt: {seconds: 1770890400}, equipment: {items: [1]} }
+     * // Output: { dbaName: "Test", createdAt: Date(...), equipment: [1] }
+     */
+    static normalizeResponse(source, updateMask) {
+        if (!source)
+            return {};
+        const result = {};
+        // Use mask paths if provided, otherwise fallback to all source keys
+        const paths = updateMask?.paths ?? Object.keys(source).map(this.toSnakeCase);
+        for (const path of paths) {
+            const parts = path.split(".");
+            let currentSrc = source;
+            let currentRes = result;
+            for (let i = 0; i < parts.length; i++) {
+                const camelKey = this.toCamelCase(parts[i]);
+                if (i === parts.length - 1) {
+                    let val = currentSrc?.[camelKey];
+                    // Unwrap nested logic
+                    if (val && typeof val === "object" && "items" in val) {
+                        val = val.items; // EquipmentInput
+                    }
+                    else if (this.isWrapper(val)) {
+                        val = val.value; // google.protobuf.Wrappers
+                    }
+                    else if (this.isTimestamp(val)) {
+                        val = new Date(Number(val.seconds) * 1000); // Timestamp
+                    }
+                    currentRes[camelKey] = val ?? null;
+                }
+                else {
+                    currentRes[camelKey] = currentRes[camelKey] || {};
+                    currentRes = currentRes[camelKey];
+                    currentSrc = currentSrc?.[camelKey];
+                }
+            }
+        }
+        delete result.id; // Primary keys should not be updated via normalization
+        return result;
+    }
+}
+exports.DataTransformer = DataTransformer;

package/dist/utils/index.d.ts

@@ -0,0 +1 @@
+export * from "./data-transformer.util";

package/dist/utils/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./data-transformer.util"), exports);