@tolinax/ayoune-interfaces 2026.44.0 → 2026.46.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/ICharge.d.ts

@@ -1,4 +1,15 @@
 import { IDefaultFields } from "./IDefaultFields";
+/**
+ * Direction of a charge entry.
+ *   - "inbound"  = customer → Tolinax  (metered usage, existing default)
+ *   - "outbound" = Tolinax → third-party provider (platform cost telemetry)
+ */
+export type ChargeDirection = "inbound" | "outbound";
+/**
+ * Known outbound providers. Kept as a string literal union rather than an
+ * enum so consumers can declare their own providers without a type release.
+ */
+export type ChargeProvider = "gcp" | "openai" | "anthropic" | "vertex" | "bitbucket" | "atlas" | "hetzner" | "cloudflare" | "npm" | string;
 export interface ICharge extends IDefaultFields {
     _customerID: ObjectId;
     _product?: ObjectId;
@@ -22,4 +33,23 @@ export interface ICharge extends IDefaultFields {
     dateTime?: Date;
     billable?: boolean;
     invoiced?: boolean;
+    /**
+     * Cost-telemetry extension (2026-04-20). All fields optional; existing
+     * inbound customer charges stay untouched. For outbound charges the
+     * `direction` field flips to "outbound" and `_customerID` is set to
+     * the TOLINAX_CUSTOMERID so multi-tenant indexes keep working without
+     * special-cases.
+     */
+    direction?: ChargeDirection;
+    provider?: ChargeProvider;
+    amountUSD?: number;
+    exchangeRate?: number;
+    /**
+     * When an outbound cost can be attributed to a specific customer (e.g.
+     * AI tokens consumed by a customer-scoped request), set this to that
+     * customer's _id. Leave undefined for platform-wide overhead.
+     */
+    attributedCustomerID?: ObjectId;
+    /** Provider-specific payload (gcp service code, openai model, etc.). */
+    meta?: any;
 }

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/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

@@ -572,6 +572,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

@@ -588,6 +588,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.44.0",
+  "version": "2026.46.0",
   "description": "Houses TypeScript interfaces for aYOUne",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",