@tolinax/ayoune-interfaces 2026.45.0 → 2026.47.0

package/data/modelNames.d.ts

@@ -538,6 +538,7 @@ export declare enum aMN {
     RunningPipelines = "RunningPipelines",
     SalesTemplates = "SalesTemplates",
     ScoreLogs = "ScoreLogs",
+    ScraperQuotaUsage = "ScraperQuotaUsage",
     SearchBars = "SearchBars",
     SearchBoxes = "SearchBoxes",
     SearchKeywords = "SearchKeywords",

package/data/modelNames.js

@@ -542,6 +542,7 @@ var aMN;
     aMN["RunningPipelines"] = "RunningPipelines";
     aMN["SalesTemplates"] = "SalesTemplates";
     aMN["ScoreLogs"] = "ScoreLogs";
+    aMN["ScraperQuotaUsage"] = "ScraperQuotaUsage";
     aMN["SearchBars"] = "SearchBars";
     aMN["SearchBoxes"] = "SearchBoxes";
     aMN["SearchKeywords"] = "SearchKeywords";

package/data/modelsAndRights.js

@@ -6291,6 +6291,19 @@ const modelsAndRights = [
         updateBy: "_id",
         availableInSDK: false,
     },
+    {
+        // Scraper Platform-Service Refactor (Phase 1) — Platform-Asset,
+        // kein _customerID-Field. Nur via api-superuser lesbar.
+        plural: "ScraperQuotaUsage",
+        singular: "ScraperQuotaUsage",
+        module: "su",
+        right: "su.scraper-quota",
+        readOnly: true,
+        importable: false,
+        allowDuplicate: false,
+        updateBy: "_id",
+        availableInSDK: false,
+    },
     {
         plural: "SearchBars",
         singular: "SearchBar",

package/interfaces/IKeywordResearch.d.ts

@@ -139,5 +139,15 @@ export interface IKeywordResearch extends IDefaultFields {
     maxCPCs: number[];
     costRuns: ICostRun[];
     results: IResults;
+    /**
+     * Scraper-Service-Tier — determiniert welcher Scraper-Provider für Jobs
+     * aus dieser KeywordResearch gewählt wird. Default 'standard'.
+     * Siehe `platform/core/src/lib/flags/README.md`.
+     */
+    scraperTier?: "economy" | "standard" | "premium";
+    /**
+     * Opt-in-Fallback auf Eigen-Infrastruktur (Phase 1.5 / Phase 7).
+     */
+    preferOwnInfra?: boolean;
 }
 export {};

package/interfaces/IMarketResearch.d.ts

@@ -84,4 +84,16 @@ export interface IMarketResearch extends IDefaultFields {
     };
     maxCPCs: number[];
     costRuns: ICostRun[];
+    /**
+     * Scraper-Service-Tier — determiniert welcher Scraper-Provider für Jobs
+     * aus dieser MarketResearch gewählt wird. Default 'standard'.
+     * Siehe `platform/core/src/lib/flags/README.md` und
+     * `crawlers/core-scraper-apis/src/lib/providerRegistry.ts`.
+     */
+    scraperTier?: "economy" | "standard" | "premium";
+    /**
+     * Opt-in-Fallback auf Eigen-Infrastruktur (Phase 1.5 / Phase 7).
+     * In Phase 1: triggert Silent-Fallback auf Nimble weil ownInfra Stub.
+     */
+    preferOwnInfra?: boolean;
 }

package/interfaces/INotification.d.ts

@@ -1,4 +1,6 @@
 import { IDefaultFields } from "./IDefaultFields";
+import { INotificationAction } from "./INotificationAction";
+import { INotificationAttachment, INotificationSender } from "./INotificationAttachment";
 export interface INotification extends IDefaultFields {
     _customerID: ObjectId;
     _clientID?: ObjectId[];
@@ -14,4 +16,22 @@ export interface INotification extends IDefaultFields {
     obj?: string;
     view?: string;
     params?: object;
+    /**
+     * Who triggered the notification. Optional — system events pass `null`
+     * and the consumer falls back to a generic `aYOUne` header.
+     */
+    sender?: INotificationSender;
+    /**
+     * Typed rich-content attachments — calendar entries, tasks, invoices,
+     * orders, etc. — rendered as inline preview cards in the notifications
+     * panel. See `INotificationAttachment` for the supported types and
+     * the enrichment contract (producer may provide `{ type, _id }` and the
+     * orchestrator fills `preview` via model lookup).
+     */
+    attachments?: INotificationAttachment[];
+    /**
+     * Action buttons rendered under the notification (1-3 typical), and —
+     * where the OS supports it — as native Web-Push action buttons (first two).
+     */
+    actions?: INotificationAction[];
 }

package/interfaces/INotificationAction.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Action buttons attached to a notification. Rendered both as inline buttons
+ * in the in-app notifications panel and (up to two primary actions) as native
+ * Web-Push action buttons on supporting platforms.
+ *
+ * Four dispatch modes:
+ *   - `link`       — internal router navigation (`href` relative to the app)
+ *   - `api`        — `fetch()` call to an absolute endpoint, optionally with
+ *                    a confirm prompt; the service-worker can execute this
+ *                    without the PWA being open (Bearer-token attached).
+ *   - `reply`      — native browser reply text field (if supported) OR a
+ *                    dialog in the PWA; the text is POSTed to `endpoint`.
+ *   - `ai-copilot` — opens the Comm-Sidebar Copilot panel with
+ *                    `copilotContext` pre-populated as the first user message.
+ */
+export type NotificationActionType = "link" | "api" | "reply" | "ai-copilot";
+/** Visual weight of the action button. */
+export type NotificationActionStyle = "primary" | "secondary" | "danger";
+export interface INotificationAction {
+    /** Stable identifier per notification — used as the Web-Push `action` id. */
+    id: string;
+    /** Button label. May be a literal or an i18n key. */
+    label: string;
+    type: NotificationActionType;
+    style?: NotificationActionStyle;
+    /** Material icon name rendered before the label. */
+    icon?: string;
+    /** For `type: "link"` — absolute or app-relative route. */
+    href?: string;
+    /** For `type: "api"` or `type: "reply"` — absolute endpoint (service-worker
+     *  executable). POST is the default for mutation-ish actions. */
+    endpoint?: string;
+    method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    /** Static payload merged with dynamic input (reply text, notification id). */
+    body?: Record<string, unknown>;
+    /** Confirmation prompt before firing (useful for destructive actions). */
+    confirmLabel?: string;
+    /** For `type: "ai-copilot"` — the prompt pre-populated into the Copilot
+     *  panel when the user taps this action. Supports `{{variable}}` tokens
+     *  that are rendered against the notification's `data` context before
+     *  being inserted into the input. */
+    copilotContext?: string;
+    /** Should this action close/dismiss the notification after firing? */
+    dismissOnComplete?: boolean;
+}

package/interfaces/INotificationAction.js

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

package/interfaces/INotificationAttachment.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Structured rich-content attachments for notifications (and — in phase 4 —
+ * chat messages). Mirrors the legacy AngularJS attachment system documented
+ * in `archive/legacy-angular1/pug/chatsidebar.pug:248-334`, where chat
+ * messages carried typed entity references (`type` + `content` + `preview`)
+ * that the renderer switched over to display inline entity cards.
+ *
+ * Producer contract:
+ *   1. The caller of `POST /notifications/send` may provide either:
+ *      - a bare reference: `{ type, _id }` — the orchestrator enriches it by
+ *        looking up the entity and projecting the relevant fields into
+ *        `preview`, OR
+ *      - a fully-formed attachment with `preview` already populated — skips
+ *        the lookup (use when the caller already has the data loaded).
+ *   2. Consumers (comm-sidebar notifications-panel, mobile-app PWA) dispatch
+ *      on `type` and render a type-specific preview component, falling back
+ *      to a generic card for unknown types.
+ *
+ * Phase 1 ships 5 core types. Subsequent phases add the remaining 12+
+ * types from the legacy chat system (document, consumer, contract,
+ * shipping, productionorder, creditnote, internalorder, offer, assignment,
+ * question, snippet, media).
+ */
+export type NotificationAttachmentType = "calendarentry" | "task" | "invoice" | "permissionrequest" | "supplierorder";
+/** Shared shape — all previews carry an optional deep-link override. */
+interface INotificationAttachmentBase {
+    /** Reference to the source entity (the document `_id`). Required for
+     *  enrichment and deep-linking. */
+    _id: ObjectId;
+    /** Optional router path used when the user taps the preview card.
+     *  When absent, the consumer falls back to `/{type}/{_id}`. */
+    href?: string;
+}
+export interface ICalendarEntryPreview extends INotificationAttachmentBase {
+    summary?: string;
+    description?: string;
+    start?: Date | string;
+    end?: Date | string;
+    typ?: string;
+    status?: string;
+    location?: string;
+    allDay?: boolean;
+    organizer?: {
+        _id?: ObjectId;
+        name?: string;
+        email?: string;
+    };
+    attendees?: Array<{
+        _id?: ObjectId;
+        name?: string;
+        email?: string;
+        rsvp?: "accepted" | "declined" | "tentative" | "pending";
+    }>;
+}
+export interface ITaskPreview extends INotificationAttachmentBase {
+    title?: string;
+    ticketIdentifier?: string;
+    status?: string;
+    priority?: string;
+    type?: string;
+    due?: Date | string;
+    assignee?: {
+        _id?: ObjectId;
+        name?: string;
+        avatar?: string;
+    };
+    project?: {
+        _id?: ObjectId;
+        name?: string;
+    };
+    points?: number;
+}
+export interface IInvoicePreview extends INotificationAttachmentBase {
+    nbr?: number;
+    referenceNumber?: string;
+    title?: string;
+    total?: number;
+    currency?: string;
+    dueDate?: Date | string;
+    paid?: boolean;
+    status?: string;
+    receiver?: {
+        _id?: ObjectId;
+        name?: string;
+    };
+}
+export interface IPermissionRequestPreview extends INotificationAttachmentBase {
+    reason?: string;
+    permissionName?: string;
+    askedOn?: Date | string;
+    fromUser?: {
+        _id?: ObjectId;
+        name?: string;
+        avatar?: string;
+    };
+    valid_from?: Date | string;
+    valid_till?: Date | string;
+    approved?: boolean;
+    declined?: boolean;
+    temporary?: boolean;
+}
+export interface ISupplierOrderPreview extends INotificationAttachmentBase {
+    nbr?: string | number;
+    shopOrderNbr?: string;
+    title?: string;
+    total?: number;
+    currency?: string;
+    confirmed?: boolean;
+    needsInternalApproval?: string;
+    internalApproved?: boolean;
+    internalDeclined?: boolean;
+    supplier?: {
+        _id?: ObjectId;
+        name?: string;
+    };
+    expectedDelivery?: Date | string;
+}
+export type INotificationAttachment = {
+    type: "calendarentry";
+    preview: ICalendarEntryPreview;
+} | {
+    type: "task";
+    preview: ITaskPreview;
+} | {
+    type: "invoice";
+    preview: IInvoicePreview;
+} | {
+    type: "permissionrequest";
+    preview: IPermissionRequestPreview;
+} | {
+    type: "supplierorder";
+    preview: ISupplierOrderPreview;
+};
+/** Producer-side shape — accepts either a bare reference (orchestrator will
+ *  enrich) or a fully-populated attachment. */
+export type INotificationAttachmentInput = {
+    type: NotificationAttachmentType;
+    _id: ObjectId;
+} | INotificationAttachment;
+/** Sender metadata carried on the notification document so the in-app panel
+ *  can show "Alice assigned you a task" with the avatar of the triggering
+ *  actor rather than a faceless system row. */
+export interface INotificationSender {
+    _userId?: ObjectId;
+    name?: string;
+    avatar?: string;
+    email?: string;
+}
+export {};

package/interfaces/INotificationAttachment.js

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * Structured rich-content attachments for notifications (and — in phase 4 —
+ * chat messages). Mirrors the legacy AngularJS attachment system documented
+ * in `archive/legacy-angular1/pug/chatsidebar.pug:248-334`, where chat
+ * messages carried typed entity references (`type` + `content` + `preview`)
+ * that the renderer switched over to display inline entity cards.
+ *
+ * Producer contract:
+ *   1. The caller of `POST /notifications/send` may provide either:
+ *      - a bare reference: `{ type, _id }` — the orchestrator enriches it by
+ *        looking up the entity and projecting the relevant fields into
+ *        `preview`, OR
+ *      - a fully-formed attachment with `preview` already populated — skips
+ *        the lookup (use when the caller already has the data loaded).
+ *   2. Consumers (comm-sidebar notifications-panel, mobile-app PWA) dispatch
+ *      on `type` and render a type-specific preview component, falling back
+ *      to a generic card for unknown types.
+ *
+ * Phase 1 ships 5 core types. Subsequent phases add the remaining 12+
+ * types from the legacy chat system (document, consumer, contract,
+ * shipping, productionorder, creditnote, internalorder, offer, assignment,
+ * question, snippet, media).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/interfaces/IScraperQuotaUsage.d.ts

@@ -0,0 +1,37 @@
+import { IDefaultFields } from "./IDefaultFields";
+import { ScraperProviderName } from "./INormalizedSerp";
+/**
+ * Scraper-Provider Monats-Quota-Verbrauch (Hot-Path-State für das
+ * Quota-Gate in der Provider-Registry).
+ *
+ * Ein Dokument pro (provider, month). `_id` ist der String
+ * `"YYYY-MM:{provider}"`, z.B. `"2026-04:nimble"`. Pro Provider-Call wird
+ * `requestsUsed` mit atomarem `$inc` hochgezählt — keine Redis-Counter,
+ * kein Sync-Worker (bei ~8 req/s Peak gesamt ist Mongo-$inc auf einem
+ * Dokument pro Provider+Monat trivial).
+ *
+ * Siehe:
+ *   - `crawlers/core-scraper-apis/src/lib/quotaGate.ts` (Hot-Path + Gate)
+ *   - `platform/core/src/lib/flags/README.md` (Pricing-Flag-Konventionen)
+ *   - Plan §1.6 + §1.9
+ *
+ * **Platform-Service-Konvention**: kein `_customerID`-Feld. Scraper-Kapazität
+ * ist Tolinax-Platform-Asset, nicht tenant-scoped. Per-Customer-Attribution
+ * des Verbrauchs läuft über Events (`scraper-request` Events mit
+ * `_customerID` im Event-Doc), nicht über ScraperQuotaUsage.
+ */
+export interface IScraperQuotaUsage extends Omit<IDefaultFields, "_id"> {
+    _id: string;
+    provider: ScraperProviderName;
+    monthStart: Date;
+    monthEnd: Date;
+    /** Snapshot aus `scraper.pricing.{provider}.monthlyQuota` zum Monatsstart */
+    quotaLimit: number;
+    /** Atomarer Counter, `$inc` pro Provider-Call */
+    requestsUsed: number;
+    /** Erhöht statt requestsUsed sobald requestsUsed > quotaLimit */
+    overageRequests: number;
+    lastUpdated: Date;
+    /** Snapshot der `scraper.pricing.{provider}.version` zum Monatsstart — für Audit-Trail */
+    pricingVersion: number;
+}

package/interfaces/IScraperQuotaUsage.js

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

package/interfaces/ISerp.d.ts

@@ -1,4 +1,5 @@
 import { IDefaultFields } from "./IDefaultFields";
+import { INormalizedSerp, ScraperProviderName } from "./INormalizedSerp";
 interface ICrawlingAgent {
     _crawlingAgent: ObjectId;
     _device: ObjectId;
@@ -111,5 +112,18 @@ export interface ISerp extends IDefaultFields {
     parsingErrors?: any;
     proxyHostName?: string;
     raw?: any;
+    /**
+     * Scraper Platform-Service Refactor (Phase 1) — welcher Provider hat
+     * dieses SERP geliefert. Legacy-Pfad-Serps haben keinen provider-Eintrag
+     * (undefined). Werte: 'nimble' | 'oxy' | 'soax' | 'ownInfra'.
+     */
+    provider?: ScraperProviderName;
+    /**
+     * Scraper Platform-Service Refactor (Phase 1) — normalisierte Provider-
+     * agnostische Repräsentation. `raw` bleibt befüllt als Forensik + für
+     * existierende `storeSEA*`-Konsumenten. Phase 4 (Storage-Decompose)
+     * migriert Konsumenten auf `normalized`.
+     */
+    normalized?: INormalizedSerp;
 }
 export {};

package/interfaces/index.d.ts

@@ -462,6 +462,8 @@ export * from "./INewsletterType";
 export * from "./INewsSource";
 export * from "./INormalizedSerp";
 export * from "./INotification";
+export * from "./INotificationAction";
+export * from "./INotificationAttachment";
 export * from "./INotificationPolicy";
 export * from "./INotificationPreference";
 export * from "./IOffer";
@@ -572,6 +574,7 @@ export * from "./IRolloutStrategy";
 export * from "./IRunningPipeline";
 export * from "./ISalesTemplate";
 export * from "./IScoreLog";
+export * from "./IScraperQuotaUsage";
 export * from "./ISearchBar";
 export * from "./ISearchBox";
 export * from "./ISearchKeyword";

package/interfaces/index.js

@@ -478,6 +478,8 @@ __exportStar(require("./INewsletterType"), exports);
 __exportStar(require("./INewsSource"), exports);
 __exportStar(require("./INormalizedSerp"), exports);
 __exportStar(require("./INotification"), exports);
+__exportStar(require("./INotificationAction"), exports);
+__exportStar(require("./INotificationAttachment"), exports);
 __exportStar(require("./INotificationPolicy"), exports);
 __exportStar(require("./INotificationPreference"), exports);
 __exportStar(require("./IOffer"), exports);
@@ -588,6 +590,7 @@ __exportStar(require("./IRolloutStrategy"), exports);
 __exportStar(require("./IRunningPipeline"), exports);
 __exportStar(require("./ISalesTemplate"), exports);
 __exportStar(require("./IScoreLog"), exports);
+__exportStar(require("./IScraperQuotaUsage"), exports);
 __exportStar(require("./ISearchBar"), exports);
 __exportStar(require("./ISearchBox"), exports);
 __exportStar(require("./ISearchKeyword"), exports);

package/package.json

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