@friggframework/core 2.0.0-next.12 → 2.0.0-next.120

package/types/associations/index.d.ts

@@ -1,20 +1,3 @@
-declare module "@friggframework/associations/model" {
-  import { Model } from "mongoose";
-
-  export class Association extends Model {
-    integrationId: string;
-    name: string;
-    type: string;
-    primaryObject: string;
-    objects: {
-      entityId: string;
-      objectType: string;
-      objId: string;
-      metadata?: object;
-    }[];
-  }
-}
-
 declare module "@friggframework/associations/association" {
   export default class Association implements IFriggAssociation {
     data: any;

package/types/core/index.d.ts

@@ -1,5 +1,5 @@
 declare module "@friggframework/core" {
-  import { SQS } from "aws-sdk";
+  import type { SendMessageCommandInput } from "@aws-sdk/client-sqs";
 
   export class Delegate implements IFriggDelegate {
     delegate: any;
@@ -26,10 +26,18 @@ declare module "@friggframework/core" {
     ): Promise<any>;
   }
 
+  export interface BatchItemFailure {
+    itemIdentifier: string;
+  }
+
+  export interface BatchItemFailuresResponse {
+    batchItemFailures: BatchItemFailure[];
+  }
+
   export class Worker implements IWorker {
     getQueueURL(params: GetQueueURLParams): Promise<string | undefined>;
 
-    run(params: { Records: any }): Promise<void>;
+    run(params: { Records: any }, context?: object): Promise<BatchItemFailuresResponse>;
 
     send(params: object & { QueueUrl: any }, delay?: number): Promise<string>;
 
@@ -38,7 +46,7 @@ declare module "@friggframework/core" {
 
   interface IWorker {
     getQueueURL(params: GetQueueURLParams): Promise<string | undefined>;
-    run(params: { Records: any }): Promise<void>;
+    run(params: { Records: any }, context?: object): Promise<BatchItemFailuresResponse>;
     send(params: object & { QueueUrl: any }, delay?: number): Promise<string>;
     sendAsyncSQSMessage(params: SendSQSMessageParams): Promise<string>;
   }
@@ -50,5 +58,5 @@ declare module "@friggframework/core" {
     QueueOwnerAWSAccountId?: string;
   };
 
-  type SendSQSMessageParams = SQS.SendMessageRequest;
+  type SendSQSMessageParams = SendMessageCommandInput;
 }

package/types/database/index.d.ts

@@ -1,3 +1,11 @@
-declare module "@friggframework/database/mongo" {
-  export function connectToDatabase(): Promise<void>;
+declare module "@friggframework/database" {
+  export const prisma: any;
+  export function connectPrisma(): Promise<any>;
+  export function disconnectPrisma(): Promise<void>;
+  export class TokenRepository {
+    constructor(params: { prismaClient: any });
+  }
+  export class WebsocketConnectionRepository {
+    constructor(params: { prismaClient: any });
+  }
 }

package/types/encrypt/index.d.ts

@@ -1,5 +1,7 @@
 declare module "@friggframework/encrypt" {
-  import { Schema } from "mongoose";
-
-  export function Encrypt(schema: Schema, options: any): void;
+  export class Cryptor {
+    constructor(params: { shouldUseAws?: boolean });
+    encrypt(plaintext: string): Promise<string>;
+    decrypt(ciphertext: string): Promise<string>;
+  }
 }

package/types/errors/index.d.ts

@@ -6,11 +6,30 @@ declare module "@friggframework/errors" {
   export class FetchError extends BaseError {
     constructor(options?: FetchErrorConstructor);
 
+    statusCode?: number;
+    method: string;
+    /** Request URL without userinfo; each query value is `REDACTED`. */
+    url: string;
+    /** Non-enumerable. The raw response, or `null`. */
+    readonly response: FetchErrorResponse | null;
+    /** Non-enumerable. The raw response body; never part of `message`. */
+    readonly body: any;
+    isTimeout?: boolean;
+    timeoutMs?: number;
+
     static create(options?: CreateFetchErrorParams): Promise<FetchError>;
   }
 
+  type FetchErrorResponse = {
+    headers?: object;
+    status?: number;
+    statusText?: string;
+    bodyUsed?: boolean;
+    text?: () => Promise<string>;
+  };
+
   type FetchErrorConstructor = {
-    resource?: string;
+    resource?: string | URL | { url: string };
     init?: Partial<{
       method: string;
       credentials: string;
@@ -19,18 +38,13 @@ declare module "@friggframework/errors" {
       body: URLSearchParams | any;
       returnFullRes: false;
     }>;
-    response?: {
-      headers?: object;
-      status?: number;
-      statusText?: string;
-      text?: () => Promise<string>;
-    };
+    response?: FetchErrorResponse | null;
+    cause?: unknown;
     responseBody?: any;
+    body?: any;
   };
 
-  type CreateFetchErrorParams = Omit<FetchErrorConstructor, "responseBody"> & {
-    body: any;
-  };
+  type CreateFetchErrorParams = FetchErrorConstructor;
 
   export class HaltError extends BaseError {
     isHaltError: boolean;

package/types/integrations/index.d.ts

@@ -1,9 +1,7 @@
 declare module "@friggframework/integrations" {
   import { Delegate, IFriggDelegate } from "@friggframework/core";
-  import { Model } from "mongoose";
-  import { EntityManager } from "@friggframework/module-plugin";
 
-  export class Integration extends Model {
+  export interface Integration {
     entities: any[];
     userId: string;
     status: string; // IntegrationStatus
@@ -19,8 +17,7 @@ declare module "@friggframework/integrations" {
 
   export class IntegrationManager
     extends Delegate
-    implements IFriggIntegrationManager
-  {
+    implements IFriggIntegrationManager {
     integration: Integration;
     primaryInstance: any;
     targetInstance: any;
@@ -56,7 +53,6 @@ declare module "@friggframework/integrations" {
       entities: { id: string; user: any },
       userId: string,
       config: any,
-      EntityManager: EntityManager
     ): Promise<any>;
 
     static getFormattedIntegration(
@@ -116,8 +112,7 @@ declare module "@friggframework/integrations" {
   }
 
   export class IntegrationConfigManager
-    implements IFriggIntegrationConfigManager
-  {
+    implements IFriggIntegrationConfigManager {
     options: IntegrationOptions[];
     primary: any;
 

package/types/logs/index.d.ts

@@ -1,5 +1,64 @@
-declare module "@friggframework/logs/logger" {
+declare module "@friggframework/core/logs" {
+  export type LogLevel = "TRACE" | "DEBUG" | "INFO" | "WARN" | "ERROR" | "FATAL";
+
+  export type LogFields = Record<string, unknown>;
+
+  export interface LogRecord {
+    readonly timestamp: string;
+    readonly level: LogLevel;
+    readonly message: string;
+    readonly logger: string;
+    readonly [key: string]: unknown;
+  }
+
+  export interface Logger {
+    readonly name: string;
+    trace(message: unknown, fields?: LogFields): void;
+    debug(message: unknown, fields?: LogFields): void;
+    info(message: unknown, fields?: LogFields): void;
+    warn(message: unknown, fields?: LogFields): void;
+    error(message: unknown, fields?: LogFields): void;
+    fatal(message: unknown, fields?: LogFields): void;
+    child(bindings: LogFields | (() => LogFields)): Logger;
+    isLevelEnabled(level: string): boolean;
+  }
+
+  export interface LogSink {
+    name: string;
+    write(record: LogRecord): void;
+    flush?(options: { signal?: AbortSignal }): Promise<void> | void;
+  }
+
+  export interface MemorySink extends LogSink {
+    readonly records: LogRecord[];
+    clear(): void;
+  }
+
+  export interface SerializedError {
+    type: string;
+    message: string;
+    code?: string | number;
+    status?: number;
+    stack?: string;
+    cause?: SerializedError | string;
+  }
+
+  export function getLogger(name?: string): Logger;
+  export function createMemorySink(options?: { install?: boolean }): MemorySink;
+  export function resetLoggerForTests(options?: {
+    level?: LogLevel | Lowercase<LogLevel>;
+    sinks?: LogSink[];
+    /** Record frigg.* WARN+ records without eventName. Kept across resets that omit it. */
+    trackViolations?: boolean;
+  }): void;
+  export function serializeError(error: unknown): SerializedError;
+  export function redactValue(value: unknown): unknown;
+  export function toSanitizedSurrogate(error: unknown): Error;
+
+  /** @deprecated Use getLogger or this.logger. */
   export function debug(...messages: any[]): void;
+  /** @deprecated Use getLogger or this.logger. */
   export function initDebugLog(...initMessages: any[]): void;
-  export function flushDebugLog(error: any): void;
+  /** @deprecated Use getLogger or this.logger. */
+  export function flushDebugLog(error?: any): void;
 }

package/types/module-plugin/index.d.ts

@@ -1,75 +1,26 @@
 declare module "@friggframework/module-plugin" {
-  import { Model } from "mongoose";
   import { Delegate, IFriggDelegate } from "@friggframework/core";
 
-  export class Credential extends Model {
-    userId: string;
-    auth_is_valid: boolean;
-    subType: string;
-    externalId: string;
+  export interface Credential {
+    id?: string;
+    userId?: string;
+    authIsValid?: boolean;
+    externalId?: string;
+    data?: any;
   }
 
-  export class EntityManager implements IFriggEntityManager {
-    static primaryEntityClass: any;
-    static entityManagerClasses: any[];
-    static entityTypes: string[];
-    static getEntitiesForUser(userId: string): Promise<any[]>;
-    static checkIsValidType(entityType: string): boolean;
-    static getEntityManagerClass(entityType?: string): any;
-
-    static getEntityManagerInstanceFromEntityId(
-      entityId: string,
-      userId: string
-    ): Promise<any>;
-  }
-
-  interface IFriggEntityManager {}
-
-  export class Entity extends Model {
-    credentialId: string;
-    subType: string;
-    userId: string;
-    name: string;
-    externalId: string;
+  export interface Entity {
+    id?: string;
+    credentialId?: string;
+    userId?: string;
+    name?: string;
+    moduleName?: string;
+    externalId?: string;
+    data?: any;
   }
 
   export type MappedEntity = Entity & { id: string; type: any };
-  export class ModuleManager extends Delegate implements IFriggModuleManager {
-    static Entity: Entity;
-    static Credential: Credential;
 
-    constructor(params: { userId: string });
-
-    static getName(): any;
-    static getInstance(params: any): Promise<any>;
-    static getEntitiesForUserId(userId: string): Promise<MappedEntity[]>;
-
-    batchCreateSyncObjects(syncObjects: any, syncManager: any): Promise<any>;
-    batchUpdateSyncObjects(syncObjects: any, syncManager: any): Promise<any>;
-    findOrCreateEntity(params: any): Promise<any>;
-    getAllSyncObjects(SyncClass: any): Promise<any>;
-    getAuthorizationRequirements(params: any): Promise<any>;
-    getEntityId(): Promise<string>;
-    getEntityOptions(): Promise<any>;
-    markCredentialsInvalid(): Promise<Credential>;
-    processAuthorizationCallback(params: any): Promise<any>;
-    testAuth(params: any): Promise<any>;
-    validateAuthorizationRequirements(): Promise<boolean>;
-  }
-
-  interface IFriggModuleManager extends IFriggDelegate {
-    getEntityId(): Promise<string>;
-    validateAuthorizationRequirements(): Promise<boolean>;
-    getAuthorizationRequirements(params: any): Promise<any>;
-    testAuth(params: any): Promise<any>;
-    processAuthorizationCallback(params: any): Promise<any>;
-    getEntityOptions(): Promise<any>;
-    findOrCreateEntity(params: any): Promise<any>;
-    getAllSyncObjects(SyncClass: any): Promise<any>;
-    batchCreateSyncObjects(syncObjects: any, syncManager: any): Promise<any>;
-    batchUpdateSyncObjects(syncObjects: any, syncManager: any): Promise<any>;
-    markCredentialsInvalid(): Promise<Credential>;
-  }
 
   export class Requester implements IFriggRequester {
     DLGT_INVALID_AUTH: string;
@@ -90,6 +41,7 @@ declare module "@friggframework/module-plugin" {
     ): Promise<any>;
     parseBody(response: any): Promise<any>;
     refreshAuth(): Promise<any>;
+    _adoptNewerCredential(): Promise<boolean>;
 
     delegate: any;
     delegateTypes: any[];
@@ -121,6 +73,7 @@ declare module "@friggframework/module-plugin" {
     _put(options: RequestOptions): Promise<any>;
     _delete(options: RequestOptions): Promise<any>;
     refreshAuth(): Promise<any>;
+    _adoptNewerCredential(): Promise<boolean>;
   }
 
   type RequestOptions = {
@@ -138,8 +91,7 @@ declare module "@friggframework/module-plugin" {
 
   export class ApiKeyRequester
     extends Requester
-    implements IFriggApiKeyRequester
-  {
+    implements IFriggApiKeyRequester {
     API_KEY_NAME: string;
     API_KEY_VALUE: any;
 
@@ -160,8 +112,7 @@ declare module "@friggframework/module-plugin" {
 
   export class BasicAuthRequester
     extends Requester
-    implements IFriggBasicAuthRequester
-  {
+    implements IFriggBasicAuthRequester {
     password: string;
     username: string;
 
@@ -189,8 +140,7 @@ declare module "@friggframework/module-plugin" {
 
   export class OAuth2Requester
     extends Requester
-    implements IFriggOAuth2Requester
-  {
+    implements IFriggOAuth2Requester {
     DLGT_TOKEN_DEAUTHORIZED: string;
     DLGT_TOKEN_UPDATE: string;
     accessTokenExpire: any;
@@ -253,6 +203,7 @@ declare module "@friggframework/module-plugin" {
     addAuthHeaders(headers: object): Promise<object>;
     isAuthenticated(): boolean;
     refreshAuth(): Promise<void>;
+    _adoptNewerCredential(): Promise<boolean>;
     getTokenFromUsernamePassword(): Promise<Token>;
     getTokenFromClientCredentials(): Promise<Token>;
   }

package/types/syncs/index.d.ts

@@ -1,18 +1,3 @@
-declare module "@friggframework/syncs/model" {
-  import { Model } from "mongoose";
-
-  export class Sync extends Model {
-    entities: any[];
-    hash: string;
-    name: string;
-    dataIdentifiers: {
-      entity: any;
-      id: object;
-      hash: string;
-    }[];
-  }
-}
-
 declare module "@friggframework/syncs/manager" {
   import Sync from "@friggframework/syncs/sync";
 
@@ -28,7 +13,6 @@ declare module "@friggframework/syncs/manager" {
     confirmCreate(
       syncObj: Sync,
       createdId: string,
-      moduleManager: any
     ): Promise<any>;
     confirmUpdate(syncObj: Sync): Promise<any>;
     createSyncDBObject(objArr: any[], entities: any[]): Promise<any>;
@@ -50,7 +34,6 @@ declare module "@friggframework/syncs/manager" {
     confirmCreate(
       syncObj: Sync,
       createdId: string,
-      moduleManager: any
     ): Promise<any>;
     confirmUpdate(syncObj: Sync): Promise<any>;
   }

package/usage/README.md

@@ -0,0 +1,54 @@
+# Usage Store
+
+The durable, Frigg-owned store behind ADR-011 feature-usage tracking. Holds
+per-integration counters that the reporting endpoint reads for cross-integration
+comparison and trend series.
+
+Populated by the telemetry usage rollup and read via `frigg.usage.*` — see
+[`telemetry/README.md`](../telemetry/README.md) for the full guide, config, and
+usage examples. This README covers the store internals only.
+
+## Fact row
+
+`UsageCounter { integrationId, integrationType, metric, window, value, updatedAt }`,
+uniquely keyed by `(integrationId, integrationType, metric, window)`. `window` is
+`day:YYYY-MM-DD` or `hour:YYYY-MM-DDTHH` (UTC).
+
+## Isolation (ADR-010 Decision 3)
+
+The store is deliberately isolated from user/integration-scoped data:
+
+- **No `userId`** and **no foreign key** to `Integration` — a user-scoped query
+  can never return a usage row, and usage history survives integration deletion.
+- **Not** in the encryption registry — dimensions are bounded and non-sensitive.
+
+## Repository triad
+
+Mirrors the reporting/process pattern — an interface plus PostgreSQL, MongoDB and
+DocumentDB adapters selected by `DB_TYPE`:
+
+```js
+const { createUsageRepository } = require('@friggframework/core'); // usage-repository-factory
+
+class UsageRepositoryInterface {
+    async increment({ integrationId, integrationType, metric, window, value }) {} // atomic upsert
+    async getTotalsByDimension({ metric, groupBy, since, bucket }) {}   // comparison (one window granularity)
+    async getTimeSeries({ metric, integrationType, from, to, bucket }) {} // trend (aggregated across instances)
+}
+```
+
+- **`increment`** is atomic: PostgreSQL uses Prisma `upsert` with
+  `{ value: { increment } }`; a concurrent first-insert race (`P2002`) retries
+  once onto the atomic update path.
+- **`getTotalsByDimension`** filters to a single window granularity (default `day`) so day and
+  hour rows are never double-summed. Requires a `metric`; `groupBy` is
+  allow-listed to `integrationType` / `metric`.
+- **`getTimeSeries`** aggregates across integration instances (`groupBy(window) + sum`)
+  and range-filters on the window key. Requires an `integrationType`.
+
+> **DocumentDB:** the adapter overrides increment/getTotalsByDimension/getTimeSeries with raw commands
+> (`$runCommandRaw`: a `$inc` upsert via `documentdb-utils.updateOne`, and a
+> cursor-drained `$aggregate` `$group/$sum`) — matching every other DocumentDB
+> adapter, since Prisma's Mongo engine emits upsert/groupBy shapes DocumentDB
+> rejects and cursor reads truncate at ~101 docs. Command shapes are unit-tested;
+> run an end-to-end check against a real cluster before GA.

package/usage/index.js

@@ -0,0 +1,17 @@
+const {
+    createUsageRepository,
+    UsageRepositoryPrisma,
+    UsageRepositoryDocumentDB,
+} = require('./repositories/usage-repository-factory');
+const {
+    UsageRepositoryInterface,
+} = require('./repositories/usage-repository-interface');
+const { computeTrackedMetrics } = require('./tracked-metrics');
+
+module.exports = {
+    createUsageRepository,
+    computeTrackedMetrics,
+    UsageRepositoryInterface,
+    UsageRepositoryPrisma,
+    UsageRepositoryDocumentDB,
+};