@friggframework/core 2.0.0-next.111 → 2.0.0-next.113

package/modules/requester/oauth-2.js

@@ -136,13 +136,13 @@ class OAuth2Requester extends Requester {
             this.refresh_token = newRefreshToken;
         } else {
             if (this.refresh_token) {
-                console.log(
-                    '[Frigg] No refresh_token in response, preserving existing'
-                );
+                this.logger.debug('No refresh_token in response, preserving existing', {
+                    eventName: `${this.logger.name}.refresh_token_preserved`,
+                });
             } else {
-                console.log(
-                    '[Frigg] Current refresh_token is null and no new refresh_token in response'
-                );
+                this.logger.debug('No refresh_token in response and none held', {
+                    eventName: `${this.logger.name}.refresh_token_absent`,
+                });
             }
         }
         const accessExpiresIn = get(params, 'expires_in', null);
@@ -265,7 +265,9 @@ class OAuth2Requester extends Requester {
                 'Content-Type': 'application/x-www-form-urlencoded',
             },
         };
-        console.log('[Frigg] Refreshing access token with options');
+        this.logger.debug('Refreshing access token', {
+            eventName: `${this.logger.name}.token_refresh_request`,
+        });
         const response = await this._post(options, false);
         await this.setTokens(response);
         return response;
@@ -323,12 +325,14 @@ class OAuth2Requester extends Requester {
         }
 
         try {
-            console.log('[Frigg] Starting token refresh', {
-                grant_type: this.grant_type,
-                has_refresh_token: !!this.refresh_token,
-                has_client_id: !!this.client_id,
-                has_client_secret: !!this.client_secret,
-                has_token_uri: !!this.tokenUri,
+            // Field names avoid the denied suffixes (token, secret), which
+            // would redact these booleans.
+            this.logger.debug('Starting token refresh', {
+                eventName: `${this.logger.name}.token_refresh_started`,
+                grantType: this.grant_type,
+                refreshTokenPresent: !!this.refresh_token,
+                clientIdPresent: !!this.client_id,
+                clientSecretPresent: !!this.client_secret,
                 tokenUri: this.tokenUri,
             });
 
@@ -343,15 +347,17 @@ class OAuth2Requester extends Requester {
                 const tokenRes = await this.getTokenFromClientCredentials();
                 if (!tokenRes) return false;
             }
-            console.log('[Frigg] Token refresh succeeded');
+            this.logger.info('Token refresh succeeded', {
+                eventName: `${this.logger.name}.token_refreshed`,
+            });
             return true;
         } catch (error) {
             const moduleName = this.delegate?.name ?? 'unknown module';
-            console.error(`[Frigg] Token refresh failed for ${moduleName}`, {
-                error_message: error?.message,
-                error_name: error?.name,
-                response_status: error?.response?.status,
-                response_data: error?.response?.data,
+            this.logger.debug('Token refresh failed', {
+                eventName: `${this.logger.name}.token_refresh_failed`,
+                statusCode:
+                    error?.statusCode ?? error?.status ?? error?.response?.status,
+                reason: error?.message,
             });
 
             if (!this._isDefinitiveAuthRejection(error)) {
@@ -405,9 +411,9 @@ class OAuth2Requester extends Requester {
         for (const delayMs of this.credentialReloadBackoffMs) {
             await new Promise((resolve) => setTimeout(resolve, delayMs));
             if (await this._adoptNewerCredential()) {
-                console.log(
-                    '[Frigg] Adopted a newer credential after a refresh rejection',
-                    { module: this._telemetryModuleLabel() }
+                this.logger.info(
+                    'Adopted a newer credential after a refresh rejection',
+                    { eventName: `${this.logger.name}.credential_adopted` }
                 );
                 this.telemetry?.count?.('frigg.auth.refresh_race_recovered', 1, {
                     module: this._telemetryModuleLabel(),

package/modules/requester/requester.js

@@ -4,8 +4,22 @@ const { Delegate } = require('../../core');
 const { FetchError } = require('../../errors');
 const { get } = require('../../assertions');
 const { getTelemetry } = require('../../telemetry/telemetry-runtime');
+const { getLogger } = require('../../logs');
+const { redactUrl } = require('../../logs/redact');
+const { toSanitizedSurrogate } = require('../../logs/serialize');
+const { getLoggerScope } = require('../../logs/context');
 
 const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
+
+// A node-fetch error message holds the raw URL, and util.inspect prints the
+// cause chain, so the FetchError keeps only a sanitized copy.
+function sanitizedCause(err) {
+    const surrogate = toSanitizedSurrogate(err);
+    for (const key of ['errno', 'type']) {
+        if (typeof err?.[key] === 'string') surrogate[key] = err[key];
+    }
+    return surrogate;
+}
 const MAX_AUTH_RETRIES = 3;
 
 // This context marks the async call chain that holds the refresh slot, and
@@ -64,6 +78,18 @@ class Requester extends Delegate {
         // `this.telemetry` to attribute out-of-band requests — setup/OAuth calls
         // made before an integration context exists aren't rolled up otherwise.
         this.telemetry = (params && params.telemetry) || getTelemetry();
+
+        // Not `get(params, 'logger')`: it throws when the key is missing.
+        this._logger = params?.logger ?? null;
+    }
+
+    // Resolved per read, so a delegate set after construction names the logger.
+    get logger() {
+        return this._logger ?? getLogger(`module.${this._telemetryModuleLabel()}`);
+    }
+
+    set logger(logger) {
+        this._logger = logger ?? null;
     }
 
     /**
@@ -141,11 +167,14 @@ class Requester extends Delegate {
 
         return telemetry.span('frigg.apimodule.request', async (span) => {
             if (span && typeof span.setAttributes === 'function') {
+                const { requestId, messageId } = getLoggerScope();
                 span.setAttributes({
                     'frigg.module': module,
                     'http.request.method': method,
                     // Redacted (no query/userinfo) — never emit raw URLs.
                     'url.path': safeUrl,
+                    ...(requestId !== undefined && { requestId }),
+                    ...(messageId !== undefined && { messageId }),
                 });
             }
             // Redacted url (unbounded) rides the bus-only context for North Star
@@ -255,15 +284,12 @@ class Requester extends Delegate {
                 const fetchError = await FetchError.create({
                     resource: encodedUrl,
                     init: options,
-                    responseBody: isTimeout
-                        ? `Request timed out after ${timeoutMs}ms`
-                        : e,
+                    cause: sanitizedCause(e),
                 });
                 if (isTimeout) {
                     // Flag + machine-readable fields so callers can
                     // distinguish a timeout from a generic network error
-                    // without parsing the message (which FetchError
-                    // sanitizes outside of STAGE=dev).
+                    // without parsing the message.
                     fetchError.isTimeout = true;
                     fetchError.timeoutMs = timeoutMs;
                 }
@@ -361,6 +387,7 @@ class Requester extends Delegate {
             // the response body (response.text()) — timer must still be
             // alive to catch a stalled body stream.
             if (status >= 400) {
+                this._logRequestFailed(encodedUrl, options, status);
                 const fetchError = await FetchError.create({
                     resource: encodedUrl,
                     init: options,
@@ -387,12 +414,25 @@ class Requester extends Delegate {
             // If the abort fired during body consumption, node-fetch emits
             // the error as an AbortError on the body stream. Surface the
             // same isTimeout flag callers use for header-phase timeouts.
-            throw this._maybeFlagTimeoutDuringBodyRead(e, timeoutMs);
+            const flagged = this._maybeFlagTimeoutDuringBodyRead(e, timeoutMs);
+            throw this._wrapFetchLibraryError(flagged, encodedUrl, options);
         } finally {
             clearRequestTimer();
         }
     }
 
+    _logRequestFailed(encodedUrl, options, status) {
+        const logger = this.logger;
+        if (!logger.isLevelEnabled('DEBUG')) return;
+        logger.debug('Request failed', {
+            eventName: `${logger.name}.request_failed`,
+            method: (options.method || 'GET').toUpperCase(),
+            url: redactUrl(encodedUrl),
+            statusCode: status,
+            headerNames: Object.keys(options.headers || {}),
+        });
+    }
+
     async _invalidateAuth(encodedUrl, options, response) {
         const fetchError = await FetchError.create({
             resource: encodedUrl,
@@ -403,6 +443,29 @@ class Requester extends Delegate {
         return fetchError;
     }
 
+    // node-fetch names its own error class FetchError too, and its message
+    // holds the raw URL. Only our class passes through unwrapped.
+    _wrapFetchLibraryError(err, encodedUrl, options) {
+        if (!err || typeof err !== 'object' || err instanceof FetchError) {
+            return err;
+        }
+        const isFetchLibraryError =
+            err.name === 'FetchError' ||
+            err.name === 'AbortError' ||
+            typeof err.type === 'string';
+        if (!isFetchLibraryError) return err;
+        const wrapped = new FetchError({
+            resource: encodedUrl,
+            init: options,
+            cause: sanitizedCause(err),
+        });
+        if (err.isTimeout) {
+            wrapped.isTimeout = true;
+            wrapped.timeoutMs = err.timeoutMs;
+        }
+        return wrapped;
+    }
+
     _maybeFlagTimeoutDuringBodyRead(err, timeoutMs) {
         if (!err || typeof err !== 'object') return err;
         if (err.isTimeout) return err;

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0-next.111",
+    "version": "2.0.0-next.113",
     "dependencies": {
         "@aws-sdk/client-apigatewaymanagementapi": "^3.588.0",
         "@aws-sdk/client-kms": "^3.588.0",
@@ -22,7 +22,6 @@
         "body-parser": "^1.20.5",
         "bson": "^4.7.2",
         "chalk": "^4.1.2",
-        "common-tags": "^1.8.2",
         "cors": "^2.8.5",
         "dotenv": "^16.4.7",
         "express": "^4.22.2",
@@ -48,9 +47,9 @@
         }
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0-next.111",
-        "@friggframework/prettier-config": "2.0.0-next.111",
-        "@friggframework/test": "2.0.0-next.111",
+        "@friggframework/eslint-config": "2.0.0-next.113",
+        "@friggframework/prettier-config": "2.0.0-next.113",
+        "@friggframework/test": "2.0.0-next.113",
         "@prisma/client": "^6.19.3",
         "@types/lodash": "4.17.15",
         "@typescript-eslint/eslint-plugin": "^8.0.0",
@@ -90,5 +89,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "6880b89cf8aa381fac9165ad0bb810347bc8a75d"
+    "gitHead": "783d9f59b16663376c313b1bb4874d5efcb54a5a"
 }

package/queues/queue-delivery.js

@@ -0,0 +1,41 @@
+const INTEGRATION_QUEUE_MAX_RECEIVE_COUNT = 3;
+const QUEUE_MAX_RECEIVE_COUNT_ENV = 'FRIGG_QUEUE_MAX_RECEIVE_COUNT';
+
+const toPositiveInteger = (value) => {
+    const number = Number(value);
+    return Number.isInteger(number) && number > 0 ? number : undefined;
+};
+
+/**
+ * @typedef {Object} QueueDelivery
+ * @property {number|undefined} receiveCount SQS ApproximateReceiveCount of this delivery.
+ * @property {number|undefined} maxReceiveCount Receives allowed before the queue dead-letters the message.
+ * @property {boolean} isLastAttempt True only when both counts are known and receiveCount >= maxReceiveCount.
+ */
+
+/**
+ * @param {Object} record SQS event record
+ * @param {Object} [env=process.env]
+ * @returns {QueueDelivery}
+ */
+const readQueueDelivery = (record, env = process.env) => {
+    const receiveCount = toPositiveInteger(
+        record?.attributes?.ApproximateReceiveCount
+    );
+    const maxReceiveCount = toPositiveInteger(env[QUEUE_MAX_RECEIVE_COUNT_ENV]);
+
+    return {
+        receiveCount,
+        maxReceiveCount,
+        isLastAttempt:
+            receiveCount !== undefined &&
+            maxReceiveCount !== undefined &&
+            receiveCount >= maxReceiveCount,
+    };
+};
+
+module.exports = {
+    INTEGRATION_QUEUE_MAX_RECEIVE_COUNT,
+    QUEUE_MAX_RECEIVE_COUNT_ENV,
+    readQueueDelivery,
+};

package/queues/queuer-util.js

@@ -1,5 +1,6 @@
 const { v4: uuid } = require('uuid');
 const { SQSClient, SendMessageCommand, SendMessageBatchCommand } = require('@aws-sdk/client-sqs');
+const { summarizeMessageBody } = require('../logs/summarize-event');
 
 const awsConfigOptions = () => {
     const config = {};
@@ -18,21 +19,6 @@ const awsConfigOptions = () => {
 
 const sqs = new SQSClient(awsConfigOptions());
 
-// Best-effort extraction of the logical event/processId/integrationId from a
-// JSON message body. Used only for log correlation — never throws.
-const summarizeMessageBody = (bodyStr) => {
-    try {
-        const parsed = JSON.parse(bodyStr);
-        return {
-            event: parsed?.event,
-            processId: parsed?.data?.processId,
-            integrationId: parsed?.data?.integrationId,
-        };
-    } catch {
-        return {};
-    }
-};
-
 // Inspect SendMessageBatchResult for partial failures and log them.
 // AWS SendMessageBatch can succeed at the HTTP level while individual entries
 // are rejected (KMS errors, per-entry throttling, service errors). Callers that

package/telemetry/bind-telemetry-context.js

@@ -67,6 +67,10 @@ function bindTelemetryContext(base, getContext) {
                 ? base.shutdown(...args)
                 : undefined,
         isEnabled: (...args) => base.isEnabled(...args),
+        getActiveSpanContext: () =>
+            typeof base.getActiveSpanContext === 'function'
+                ? base.getActiveSpanContext()
+                : null,
     };
 }
 

package/telemetry/instrument-handler.js

@@ -1,3 +1,5 @@
+const { getLoggerScope, runInContext } = require('../logs/context');
+
 /**
  * Wraps a single integration handler invocation with a span + the
  * `frigg.handler.invocations` counter. Shared by the two
@@ -16,6 +18,15 @@
  * @param {{event: string, eventType: string}} descriptor Event name + bounded type.
  * @param {Function} fn The handler invocation.
  */
+// The trace link to the logs (ADR-048 §7): span attributes only, never labels.
+function scopeIdAttributes() {
+    const { requestId, messageId } = getLoggerScope();
+    const attributes = {};
+    if (requestId !== undefined && requestId !== null) attributes.requestId = requestId;
+    if (messageId !== undefined && messageId !== null) attributes.messageId = messageId;
+    return attributes;
+}
+
 async function instrumentHandler(telemetry, descriptor = {}, fn) {
     if (!telemetry || typeof telemetry.span !== 'function') {
         return fn();
@@ -36,6 +47,7 @@ async function instrumentHandler(telemetry, descriptor = {}, fn) {
                     integration_type: integrationType,
                     event: eventType,
                     event_name: eventName,
+                    ...scopeIdAttributes(),
                 });
             }
             // `event_name` (potentially high-cardinality action id) rides the
@@ -70,6 +82,11 @@ async function instrumentHandler(telemetry, descriptor = {}, fn) {
             }
         });
 
+    // The logger scope goes straight into the one store, so a custom
+    // telemetry service never sees the logger sub-object.
+    const runInLoggerScope = () =>
+        runInContext({ log: { integrationEvent: eventName } }, runInstrumented);
+
     if (typeof telemetry.withContext === 'function') {
         return telemetry.withContext(
             {
@@ -78,10 +95,10 @@ async function instrumentHandler(telemetry, descriptor = {}, fn) {
                 integrationType: context.integrationType,
                 version: context.version,
             },
-            runInstrumented
+            runInLoggerScope
         );
     }
-    return runInstrumented();
+    return runInLoggerScope();
 }
 
 module.exports = { instrumentHandler };

package/telemetry/no-op-telemetry.js

@@ -62,6 +62,10 @@ class NoOpTelemetry {
     isEnabled() {
         return false;
     }
+
+    getActiveSpanContext() {
+        return null;
+    }
 }
 
 module.exports = { NoOpTelemetry };

package/telemetry/otel-telemetry.js

@@ -17,6 +17,11 @@ const {
     runWithTelemetryContext,
     mergeTelemetryContext,
 } = require('./telemetry-context');
+const { serializeError } = require('../logs/serialize');
+const { LOGGER_SCOPE_KEY } = require('../logs/context');
+
+const BAGGAGE_TYPES = new Set(['string', 'number', 'boolean', 'bigint']);
+const isBaggageValue = (value) => BAGGAGE_TYPES.has(typeof value);
 
 const TRACER_NAME = 'frigg';
 const METRIC_EXPORT_INTERVAL_MS =
@@ -138,6 +143,15 @@ class OtelTelemetry {
         this._bus.emit('event', payload);
     }
 
+    getActiveSpanContext() {
+        const spanContext = otelApi.trace.getActiveSpan()?.spanContext();
+        if (!spanContext || !otelApi.isSpanContextValid(spanContext)) {
+            return null;
+        }
+        const { traceId, spanId, traceFlags } = spanContext;
+        return { traceId, spanId, traceFlags };
+    }
+
     startSpan(name, options) {
         return this._tracer.startSpan(name, options);
     }
@@ -150,10 +164,16 @@ class OtelTelemetry {
                 span.setStatus({ code: otelApi.SpanStatusCode.OK });
                 return result;
             } catch (err) {
-                span.recordException(err);
+                const serialized = serializeError(err);
+                span.recordException({
+                    name: serialized.type,
+                    message: serialized.message,
+                    stack: serialized.stack,
+                    code: serialized.code,
+                });
                 span.setStatus({
                     code: otelApi.SpanStatusCode.ERROR,
-                    message: err && err.message,
+                    message: serialized.message,
                 });
                 throw err;
             } finally {
@@ -170,10 +190,9 @@ class OtelTelemetry {
      */
     async withContext(attributes = {}, fn) {
         const entries = {};
-        for (const [key, value] of Object.entries(attributes)) {
-            if (value !== undefined && value !== null) {
-                entries[key] = { value: String(value) };
-            }
+        for (const [key, value] of Object.entries(attributes || {})) {
+            if (key === LOGGER_SCOPE_KEY || !isBaggageValue(value)) continue;
+            entries[key] = { value: String(value) };
         }
         const baggage = otelApi.propagation.createBaggage(entries);
         const ctx = otelApi.propagation.setBaggage(

package/telemetry/telemetry-context.js

@@ -1,8 +1,13 @@
-const { AsyncLocalStorage } = require('node:async_hooks');
+const {
+    runInContext,
+    getContext,
+    hasOnlyLoggerKeys,
+    LOGGER_SCOPE_KEY,
+} = require('../logs/context');
 
 /**
- * Ambient telemetry context. A single process-wide AsyncLocalStorage
- * holds the standard identifiers ({integrationId, integrationType, userId,
+ * Ambient telemetry context. The one process-wide AsyncLocalStorage
+ * (owned by logs/context.js, shared with the logger scope) holds the standard identifiers ({integrationId, integrationType, userId,
  * version, ...}) for the duration of a handler, set once at the handler seam via
  * `telemetry.withContext(...)`. Any emission during that async scope — including
  * deep calls like an API-module request — reads the ambient context, so the
@@ -11,24 +16,30 @@ const { AsyncLocalStorage } = require('node:async_hooks');
  * on the no-op path). This is the propagation mechanism the plan intended.
  *
  * Only bus-payload `context` is populated from here; high-cardinality ids never
- * touch OTel metric labels.
+ * touch OTel metric labels. A nested run merges: an undefined key keeps the
+ * outer value, an explicit null is stored as null.
  */
-const store = new AsyncLocalStorage();
+function withoutLoggerKeys(store) {
+    if (!store || hasOnlyLoggerKeys(store)) return null;
+    const { [LOGGER_SCOPE_KEY]: _logger, ...rest } = store;
+    return rest;
+}
 
 function runWithTelemetryContext(context, fn) {
-    return store.run(context || {}, fn);
+    return runInContext(context, fn);
 }
 
 function getTelemetryContextStore() {
-    return store.getStore() || null;
+    return withoutLoggerKeys(getContext());
 }
 
 /**
  * Merge the ambient context with an explicit per-call context (explicit keys
  * win, e.g. a request `url`). Returns undefined when there is nothing to attach.
+ * The logger sub-object never reaches the bus payload.
  */
 function mergeTelemetryContext(explicit) {
-    const ambient = store.getStore();
+    const ambient = withoutLoggerKeys(getContext());
     if (!ambient && !explicit) return undefined;
     return { ...(ambient || {}), ...(explicit || {}) };
 }

package/telemetry/telemetry-runtime.js

@@ -7,6 +7,7 @@
 
 const { createTelemetry } = require('./telemetry-service');
 const { NoOpTelemetry } = require('./no-op-telemetry');
+const loggerRuntime = require('../logs/logger-runtime');
 
 const UNSET = Symbol('unset');
 
@@ -21,12 +22,27 @@ function loadTelemetryConfig() {
     return loadAppDefinition();
 }
 
+function activeSpanContext() {
+    const telemetry = state.telemetry;
+    return telemetry && typeof telemetry.getActiveSpanContext === 'function'
+        ? telemetry.getActiveSpanContext()
+        : null;
+}
+
+// resetLoggerForTests clears the provider, so check on every call.
+function ensureSpanContextProvider() {
+    if (loggerRuntime.getSpanContextProvider() !== activeSpanContext) {
+        loggerRuntime.setSpanContextProvider(activeSpanContext);
+    }
+}
+
 /**
  * The process telemetry service. Created lazily on first use and reused for the
  * life of the Lambda container, so the OTel SDK initialises at most once per cold
  * start. Never throws — any failure falls back to the no-op.
  */
 function getTelemetry() {
+    ensureSpanContextProvider();
     if (state.telemetry) return state.telemetry;
     try {
         const { telemetry = {} } = loadTelemetryConfig();
@@ -136,6 +152,7 @@ function resetTelemetryRuntimeForTests() {
 function setTelemetryForTests(telemetry) {
     state = newState();
     state.telemetry = telemetry;
+    ensureSpanContextProvider();
 }
 
 module.exports = {

package/telemetry/telemetry-service.js

@@ -8,6 +8,7 @@ const { createTelemetryEventBus } = require('./telemetry-event-bus');
  *   count(name, value?, attributes?, context?) · event(name, attributes?, context?)
  *   span(name, fn) · startSpan(name?) · withContext(context, fn)
  *   on(eventType, cb) · forceFlush() · shutdown() · isEnabled()
+ *   getActiveSpanContext() → { traceId, spanId, traceFlags } | null
  */
 
 /**

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;