@tolinax/ayoune-interfaces 2026.29.0 → 2026.30.0

package/data/modelNames.d.ts

@@ -613,6 +613,9 @@ export declare enum aMN {
     TextLinks = "TextLinks",
     Tickets = "Tickets",
     Tips = "Tips",
+    TradeChannelEvents = "TradeChannelEvents",
+    TradeChannelOrders = "TradeChannelOrders",
+    TradeChannels = "TradeChannels",
     Trades = "Trades",
     Transactions = "Transactions",
     TransportOrders = "TransportOrders",

package/data/modelNames.js

@@ -617,6 +617,9 @@ var aMN;
     aMN["TextLinks"] = "TextLinks";
     aMN["Tickets"] = "Tickets";
     aMN["Tips"] = "Tips";
+    aMN["TradeChannelEvents"] = "TradeChannelEvents";
+    aMN["TradeChannelOrders"] = "TradeChannelOrders";
+    aMN["TradeChannels"] = "TradeChannels";
     aMN["Trades"] = "Trades";
     aMN["Transactions"] = "Transactions";
     aMN["TransportOrders"] = "TransportOrders";

package/data/modelsAndRights.js

@@ -6696,6 +6696,64 @@ const modelsAndRights = [
         allowDuplicate: false,
         updateBy: "_id",
     },
+    {
+        plural: "TradeChannels",
+        singular: "TradeChannel",
+        module: "purchase",
+        right: "purchase.tradechannels",
+        readOnly: false,
+        importable: false,
+        allowDuplicate: false,
+        updateBy: "_id",
+        searchable: true,
+        searchableFields: ["label", "externalAccountId", "provider"],
+    },
+    {
+        plural: "TradeChannelOrders",
+        singular: "TradeChannelOrder",
+        module: "purchase",
+        right: "purchase.tradechannelorders",
+        readOnly: false,
+        importable: false,
+        allowDuplicate: false,
+        updateBy: "_id",
+        searchable: true,
+        searchableFields: ["externalId", "provider", "status", "counterparty.name"],
+        actions: [
+            {
+                title: "Refresh from provider",
+                action: "refresh",
+                availability: "single",
+                method: "POST",
+                icon: "refresh",
+            },
+            {
+                title: "Match products",
+                action: "match-products",
+                availability: "both",
+                method: "POST",
+                icon: "link",
+            },
+            {
+                title: "Promote to SupplierOrder",
+                action: "promote",
+                availability: "single",
+                method: "POST",
+                icon: "upgrade",
+                confirmation: "Promote this trade-channel order into a SupplierOrder + GoodsReceipt? This cannot be undone.",
+            },
+        ],
+    },
+    {
+        plural: "TradeChannelEvents",
+        singular: "TradeChannelEvent",
+        module: "purchase",
+        right: "purchase.tradechannelevents",
+        readOnly: true,
+        importable: false,
+        allowDuplicate: false,
+        updateBy: "_id",
+    },
 ];
 exports.modelsAndRights = modelsAndRights;
 exports.default = modelsAndRights;

package/interfaces/ITradeChannel.d.ts

@@ -0,0 +1,64 @@
+import { IDefaultFields } from "./IDefaultFields";
+/**
+ * Provider identifier for an external trade channel.
+ * Add new providers here as integrations land.
+ */
+export type TradeChannelProvider = "aliexpress" | "amazon" | "ebay" | "etsy" | "otto" | "bol" | "kaufland" | "tiktokshop" | "shein";
+export type TradeChannelStatus = "unconfigured" | "connected" | "disconnected" | "error" | "expired";
+/**
+ * What this channel can do for the customer. Both flows are independent
+ * because some providers expose only one side (e.g. Amazon retail has no
+ * public buy API — buy is "scrape" only, sell is full SP-API).
+ */
+export interface ITradeChannelCapabilities {
+    canBuy: "api" | "scrape" | "none";
+    canSell: "api" | "none";
+}
+/**
+ * One (customer × provider × external account) connection.
+ * A customer can have multiple AliExpress accounts, etc. — each is its own
+ * TradeChannel row, scoped via externalAccountId.
+ *
+ * Credentials never live here directly. The `_credential` ObjectId points
+ * to the standard Credentials collection (AES-256-CTR encrypted).
+ */
+export interface ITradeChannel extends IDefaultFields {
+    _customerID: ObjectId;
+    _clientID?: ObjectId[];
+    _subID?: ObjectId[];
+    provider: TradeChannelProvider;
+    /**
+     * Provider-side account identifier (e.g. AliExpress login email,
+     * Amazon seller ID, eBay user id). Allows multiple accounts per
+     * customer × provider. Required for the unique index.
+     */
+    externalAccountId: string;
+    /** Human-readable label shown in admin-v2 (e.g. "AliExpress (max@firma.de)"). */
+    label?: string;
+    status: TradeChannelStatus;
+    capabilities: ITradeChannelCapabilities;
+    /** Reference to encrypted credentials in the Credentials collection. */
+    _credential?: ObjectId;
+    /** Per-channel sync settings. */
+    settings?: {
+        /** Whether scraped/imported orders should auto-promote to SupplierOrder. Default false. */
+        autoPromote?: boolean;
+        /** Sync schedule for the per-provider worker. Default "manual". */
+        syncSchedule?: "manual" | "hourly" | "daily" | "weekly";
+        /** Default destination warehouse for buy-side dropship orders. */
+        defaultWarehouse?: ObjectId;
+    };
+    /** Last successful sync timestamps per direction. */
+    lastSyncedAt?: {
+        inbound?: Date;
+        outbound?: Date;
+    };
+    /** Last error message + timestamp from a failed sync run. */
+    lastError?: {
+        at: Date;
+        message: string;
+        code?: string;
+    };
+    /** Free-form provider-specific config (rate limits, marketplace ids, fulfillment templates, etc). */
+    providerConfig?: any;
+}

package/interfaces/ITradeChannel.js

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

package/interfaces/ITradeChannelEvent.d.ts

@@ -0,0 +1,31 @@
+import { IDefaultFields } from "./IDefaultFields";
+import { TradeChannelProvider } from "./ITradeChannel";
+/**
+ * Channel-level event (not order-level — order events live on the order
+ * document itself in `events[]`).
+ *
+ * Captures: token refreshes, sync runs, webhook receipts, OAuth callbacks,
+ * connection tests, errors. Append-only with TTL 90d (set in Mongoose model).
+ */
+export type TradeChannelEventType = "channel-created" | "oauth-started" | "oauth-completed" | "oauth-failed" | "token-refreshed" | "token-refresh-failed" | "sync-started" | "sync-completed" | "sync-failed" | "test-connection" | "webhook-received" | "import-batch" | "disconnected" | "error";
+export type TradeChannelEventSeverity = "info" | "warn" | "error";
+export interface ITradeChannelEvent extends IDefaultFields {
+    _customerID: ObjectId;
+    _clientID?: ObjectId[];
+    _subID?: ObjectId[];
+    _channel: ObjectId;
+    provider: TradeChannelProvider;
+    type: TradeChannelEventType;
+    severity: TradeChannelEventSeverity;
+    message?: string;
+    code?: string;
+    /** Optional structured payload (sync stats, webhook body summary, etc). */
+    data?: any;
+    /** Filled by import endpoint: how many orders the batch touched. */
+    counts?: {
+        created?: number;
+        updated?: number;
+        skipped?: number;
+        failed?: number;
+    };
+}

package/interfaces/ITradeChannelEvent.js

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

package/interfaces/ITradeChannelOrder.d.ts

@@ -0,0 +1,143 @@
+import { IDefaultFields } from "./IDefaultFields";
+import { TradeChannelProvider } from "./ITradeChannel";
+/**
+ * Direction of the order from the customer's perspective.
+ * - outbound: WE bought something from the provider (dropship, sourcing).
+ * - inbound:  WE sold something via the provider (we are the seller).
+ */
+export type TradeChannelOrderDirection = "outbound" | "inbound";
+/**
+ * Where this order's data came from.
+ * - provider-api: pulled via official API (DS API, SP-API, eBay Sell, Etsy OpenAPI).
+ * - plugin-scrape: scraped by the aYOUne Companion browser extension.
+ * - provider-webhook: pushed by the provider via webhook.
+ * - manual: hand-entered in admin-v2.
+ */
+export type TradeChannelOrderSource = "provider-api" | "plugin-scrape" | "provider-webhook" | "manual";
+export type TradeChannelOrderStatus = "placed" | "paid" | "processing" | "shipped" | "delivered" | "completed" | "cancelled" | "refunded" | "dispute" | "unknown";
+/**
+ * Single line item on a trade-channel order. Provider-agnostic.
+ * `_product` is filled by the post-import "match-products" worker when
+ * the external SKU/product can be linked to a Products entry.
+ */
+export interface ITradeChannelOrderItem {
+    externalProductId: string;
+    externalSkuId?: string;
+    title: string;
+    qty: number;
+    unitPrice: number;
+    lineTotal?: number;
+    currency?: string;
+    thumbnailUrl?: string;
+    productUrl?: string;
+    /** Filled when the line item is matched to an internal Product. */
+    _product?: ObjectId;
+    /** Filled when the line item is matched to an internal SKU. */
+    _sku?: ObjectId;
+    /** Provider-specific extras (variant attributes, options, etc). */
+    attributes?: Record<string, any>;
+}
+/**
+ * Tracking / shipment data for one parcel on this order.
+ */
+export interface ITradeChannelOrderShipment {
+    carrier?: string;
+    trackingNumber?: string;
+    trackingUrl?: string;
+    shippedAt?: Date;
+    estimatedDelivery?: Date;
+    deliveredAt?: Date;
+    status?: string;
+}
+/**
+ * Append-only event log entry on the order. Captures every meaningful
+ * change so we can audit who-changed-what across the api/scraper/webhook
+ * pipelines and de-duplicate confidently.
+ */
+export interface ITradeChannelOrderEvent {
+    at: Date;
+    source: TradeChannelOrderSource;
+    type: string;
+    data?: any;
+}
+/**
+ * Full shipping address record. Stored in full per the user's choice
+ * (no hashing) — required for fulfillment on the sell side and for
+ * dropship destination on the buy side.
+ */
+export interface ITradeChannelAddress {
+    company?: string;
+    salutation?: string;
+    firstName?: string;
+    lastName?: string;
+    street?: string;
+    houseNumber?: string;
+    addressAdditional?: string;
+    zip?: string;
+    city?: string;
+    state?: string;
+    country?: string;
+    countryCode?: string;
+    phone?: string;
+    email?: string;
+}
+/**
+ * One order flowing through a trade channel — bidirectional via `direction`.
+ * Unique per (customerId, _channel, externalId) so the same provider order
+ * id can never be inserted twice regardless of which pipeline reported it.
+ */
+export interface ITradeChannelOrder extends IDefaultFields {
+    _customerID: ObjectId;
+    _clientID?: ObjectId[];
+    _subID?: ObjectId[];
+    /** Reference to the TradeChannel this order flows through. */
+    _channel: ObjectId;
+    /** Cached provider for fast queries without joining _channel. */
+    provider: TradeChannelProvider;
+    direction: TradeChannelOrderDirection;
+    source: TradeChannelOrderSource;
+    /** Provider-side order id. Unique within (_customerID, _channel). */
+    externalId: string;
+    externalUrl?: string;
+    status: TradeChannelOrderStatus;
+    /** Raw provider status string before normalization. */
+    rawStatus?: string;
+    orderDate: Date;
+    currency: string;
+    subtotal?: number;
+    shippingTotal?: number;
+    taxTotal?: number;
+    discountTotal?: number;
+    total: number;
+    /** Counterparty: the seller on outbound (we bought from them) or the buyer on inbound (we sold to them). */
+    counterparty?: {
+        externalId?: string;
+        name?: string;
+        storeUrl?: string;
+        email?: string;
+    };
+    /** Shipping address — full record per user choice (no hashing). */
+    shippingAddress?: ITradeChannelAddress;
+    /** Billing address if it differs. */
+    billingAddress?: ITradeChannelAddress;
+    items: ITradeChannelOrderItem[];
+    shipments?: ITradeChannelOrderShipment[];
+    events?: ITradeChannelOrderEvent[];
+    /** First time this order was seen by aYOUne (set on insert, never updated). */
+    firstSeenAt: Date;
+    firstSeenSource: TradeChannelOrderSource;
+    /** Last time any pipeline touched this order. */
+    lastSyncedAt?: Date;
+    /** When this order was promoted into a SupplierOrder (manual action only). */
+    promotedAt?: Date;
+    /** The SupplierOrder created from this trade-channel order, if promoted. */
+    _supplierOrder?: ObjectId;
+    /** The IncomeInvoice linked to the promotion, if any. */
+    _incomeInvoice?: ObjectId;
+    /** The GoodsReceipt linked to the promotion, if any. */
+    _goodsReceipt?: ObjectId;
+    /** Last raw payload from the provider/scraper, for debugging + diffing. */
+    raw?: any;
+    /** Free-form notes (admin-entered). */
+    note?: string;
+}

package/interfaces/ITradeChannelOrder.js

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

package/interfaces/index.d.ts

@@ -653,6 +653,9 @@ export * from "./ITicket";
 export * from "./ITip";
 export * from "./ITitle";
 export * from "./ITrade";
+export * from "./ITradeChannel";
+export * from "./ITradeChannelEvent";
+export * from "./ITradeChannelOrder";
 export * from "./ITransaction";
 export * from "./ITransportOrder";
 export * from "./ITravel";

package/interfaces/index.js

@@ -669,6 +669,9 @@ __exportStar(require("./ITicket"), exports);
 __exportStar(require("./ITip"), exports);
 __exportStar(require("./ITitle"), exports);
 __exportStar(require("./ITrade"), exports);
+__exportStar(require("./ITradeChannel"), exports);
+__exportStar(require("./ITradeChannelEvent"), exports);
+__exportStar(require("./ITradeChannelOrder"), exports);
 __exportStar(require("./ITransaction"), exports);
 __exportStar(require("./ITransportOrder"), exports);
 __exportStar(require("./ITravel"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tolinax/ayoune-interfaces",
-  "version": "2026.29.0",
+  "version": "2026.30.0",
   "description": "Houses TypeScript interfaces for aYOUne",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",