@oxy.so/core 1.0.1 → 1.1.0

package/dist/esm/OxyServices.errors.js

@@ -80,6 +80,32 @@ export class ServiceAssetMetadataError extends Error {
         this.cause = cause;
     }
 }
+/**
+ * A chunk of `POST /assets/service/linked-url` failed, so the SDK cannot say
+ * whether those ids have URLs.
+ *
+ * Its own class rather than a reuse of {@link ServiceAssetMetadataError}, and
+ * deliberately WITHOUT that one's `{ partial: true }` escape hatch, because the
+ * two mistakes cost different things. Reading a failed metadata lookup as
+ * "absent" embedded a media item with no hash. Reading a failed DOWNLOAD mint as
+ * "absent" tells a buyer who paid that the file they own is not there — and
+ * "not there" is already this route's answer for "not yours", so a best-effort
+ * mode would make a throttled request indistinguishable from a refusal. There is
+ * no download path that legitimately wants that, so there is no option to ask
+ * for it.
+ */
+export class ServiceLinkedDownloadUrlError extends Error {
+    constructor(unresolvedIds, statuses, cause) {
+        const uniqueStatuses = Array.from(new Set(statuses)).sort((a, b) => a - b);
+        const statusSuffix = uniqueStatuses.length > 0 ? ` — status ${uniqueStatuses.join(', ')}` : '';
+        super(`Could not mint download URLs for ${unresolvedIds.length} id(s)${statusSuffix}. Treat this as unknown, never as "the caller holds no right".`);
+        this.code = 'SERVICE_LINKED_DOWNLOAD_URL_UNRESOLVED';
+        this.name = 'ServiceLinkedDownloadUrlError';
+        this.unresolvedIds = unresolvedIds;
+        this.statuses = uniqueStatuses;
+        this.cause = cause;
+    }
+}
 export class OxyAuthenticationTimeoutError extends OxyAuthenticationError {
     constructor(operationName, timeoutMs) {
         super(`Authentication timeout (${timeoutMs}ms): ${operationName} requires user authentication. Please ensure the user is logged in before calling this method.`, 'AUTH_TIMEOUT', 408);

package/dist/esm/i18n/locales/en-US.json

@@ -2127,6 +2127,18 @@
             "title": "Permissions requested",
             "basic": "Sign you in and read your basic profile"
         },
+        "resource": {
+            "title": "Oxy app and protected resource"
+        },
+        "writeActions": {
+            "title": "Actions this connection can perform"
+        },
+        "effects": {
+            "write": "Write",
+            "external": "External",
+            "financial": "Financial",
+            "security": "Security"
+        },
         "scopes": {
             "openid": "Confirm your identity",
             "profile": "Read your basic profile",
@@ -2147,7 +2159,8 @@
             "federationWrite": "Act across federated services"
         },
         "account": {
-            "title": "Signing in as"
+            "title": "Signing in as",
+            "id": "Account ID: {{id}}"
         },
         "links": {
             "website": "Website",

package/dist/esm/i18n/locales/es-ES.json

@@ -2127,6 +2127,18 @@
             "title": "Permisos solicitados",
             "basic": "Iniciar sesión y leer tu perfil básico"
         },
+        "resource": {
+            "title": "App de Oxy y recurso protegido"
+        },
+        "writeActions": {
+            "title": "Acciones que puede realizar esta conexión"
+        },
+        "effects": {
+            "write": "Escritura",
+            "external": "Externa",
+            "financial": "Financiera",
+            "security": "Seguridad"
+        },
         "scopes": {
             "openid": "Confirmar tu identidad",
             "profile": "Leer tu perfil básico",
@@ -2147,7 +2159,8 @@
             "federationWrite": "Actuar en servicios federados"
         },
         "account": {
-            "title": "Iniciando sesión como"
+            "title": "Iniciando sesión como",
+            "id": "ID de cuenta: {{id}}"
         },
         "links": {
             "website": "Sitio web",

package/dist/esm/i18n/locales/locales/en-US.json

@@ -2127,6 +2127,18 @@
       "title": "Permissions requested",
       "basic": "Sign you in and read your basic profile"
     },
+    "resource": {
+      "title": "Oxy app and protected resource"
+    },
+    "writeActions": {
+      "title": "Actions this connection can perform"
+    },
+    "effects": {
+      "write": "Write",
+      "external": "External",
+      "financial": "Financial",
+      "security": "Security"
+    },
     "scopes": {
       "openid": "Confirm your identity",
       "profile": "Read your basic profile",
@@ -2147,7 +2159,8 @@
       "federationWrite": "Act across federated services"
     },
     "account": {
-      "title": "Signing in as"
+      "title": "Signing in as",
+      "id": "Account ID: {{id}}"
     },
     "links": {
       "website": "Website",

package/dist/esm/i18n/locales/locales/es-ES.json

@@ -2127,6 +2127,18 @@
       "title": "Permisos solicitados",
       "basic": "Iniciar sesión y leer tu perfil básico"
     },
+    "resource": {
+      "title": "App de Oxy y recurso protegido"
+    },
+    "writeActions": {
+      "title": "Acciones que puede realizar esta conexión"
+    },
+    "effects": {
+      "write": "Escritura",
+      "external": "Externa",
+      "financial": "Financiera",
+      "security": "Seguridad"
+    },
     "scopes": {
       "openid": "Confirmar tu identidad",
       "profile": "Leer tu perfil básico",
@@ -2147,7 +2159,8 @@
       "federationWrite": "Actuar en servicios federados"
     },
     "account": {
-      "title": "Iniciando sesión como"
+      "title": "Iniciando sesión como",
+      "id": "ID de cuenta: {{id}}"
     },
     "links": {
       "website": "Sitio web",

package/dist/esm/mixins/OxyServices.agency.js

@@ -0,0 +1,110 @@
+import { CACHE_TIMES } from './mixinHelpers.js';
+function query(path, key, value) {
+    return `${path}?${key}=${encodeURIComponent(value)}`;
+}
+export function OxyServicesAgencyMixin(Base) {
+    return class extends Base {
+        async listAvailableCapabilityCatalogs(accountId) {
+            try {
+                const response = await this.makeRequest('GET', query('/capabilities/catalogs/available', 'accountId', accountId), undefined, { cache: true, cacheTTL: CACHE_TIMES.MEDIUM });
+                return response.catalogs;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        async listDelegationGrants(ownerAccountId) {
+            try {
+                const response = await this.makeRequest('GET', query('/capabilities/grants', 'ownerAccountId', ownerAccountId), undefined, { cache: true, cacheTTL: CACHE_TIMES.SHORT });
+                return response.grants;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        async createDelegationGrant(input) {
+            try {
+                const response = await this.makeRequest('POST', '/capabilities/grants', input, { cache: false });
+                this.clearCacheEntry(`GET:/capabilities/grants?ownerAccountId=${encodeURIComponent(input.ownerAccountId)}`);
+                return response.grant;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        async revokeDelegationGrant(grantId, ownerAccountId) {
+            try {
+                await this.makeRequest('DELETE', `/capabilities/grants/${encodeURIComponent(grantId)}`, undefined, { cache: false });
+                this.clearCacheEntry(`GET:/capabilities/grants?ownerAccountId=${encodeURIComponent(ownerAccountId)}`);
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        async updateDelegationGrant(grantId, ownerAccountId, input) {
+            try {
+                const response = await this.makeRequest('PUT', `/capabilities/grants/${encodeURIComponent(grantId)}`, input, { cache: false });
+                this.clearCacheEntry(`GET:/capabilities/grants?ownerAccountId=${encodeURIComponent(ownerAccountId)}`);
+                return response.grant;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        async listAccountCapabilityPolicies(accountId) {
+            try {
+                const response = await this.makeRequest('GET', query('/capabilities/account-policies', 'accountId', accountId), undefined, { cache: true, cacheTTL: CACHE_TIMES.SHORT });
+                return response.policies;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        async putAccountCapabilityPolicy(appId, input) {
+            try {
+                const response = await this.makeRequest('PUT', `/capabilities/account-policies/${encodeURIComponent(appId)}`, input, { cache: false });
+                this.clearCacheEntry(`GET:/capabilities/account-policies?accountId=${encodeURIComponent(input.accountId)}`);
+                return response.policy;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        async deleteAccountCapabilityPolicy(appId, accountId) {
+            try {
+                await this.makeRequest('DELETE', `/capabilities/account-policies/${encodeURIComponent(appId)}?accountId=${encodeURIComponent(accountId)}`, undefined, { cache: false });
+                this.clearCacheEntry(`GET:/capabilities/account-policies?accountId=${encodeURIComponent(accountId)}`);
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        async listCapabilityExecutionAuthorizations(ownerAccountId) {
+            try {
+                const response = await this.makeRequest('GET', query('/capabilities/execution-authorizations', 'ownerAccountId', ownerAccountId), undefined, { cache: true, cacheTTL: CACHE_TIMES.SHORT });
+                return response.authorizations;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        async revokeCapabilityExecutionAuthorization(authorizationId, ownerAccountId) {
+            try {
+                await this.makeRequest('DELETE', `/capabilities/execution-authorizations/${encodeURIComponent(authorizationId)}`, undefined, { cache: false });
+                this.clearCacheEntry(`GET:/capabilities/execution-authorizations?ownerAccountId=${encodeURIComponent(ownerAccountId)}`);
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        async listCapabilityAuditEvents(accountId) {
+            try {
+                const response = await this.makeRequest('GET', query('/capabilities/audit', 'accountId', accountId), undefined, { cache: true, cacheTTL: CACHE_TIMES.SHORT });
+                return response.events;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+    };
+}

package/dist/esm/mixins/OxyServices.assets.js

@@ -1,6 +1,6 @@
 import { isReactNative } from '@oxy.so/protocol';
 import { logger } from '../logger/index.js';
-import { AssetUrlResolutionError, ServiceAssetMetadataError } from '../OxyServices.errors.js';
+import { AssetUrlResolutionError, ServiceAssetMetadataError, ServiceLinkedDownloadUrlError } from '../OxyServices.errors.js';
 import { extractErrorStatus } from '../utils/errorUtils.js';
 /**
  * Maximum number of ids sent per `POST /assets/service/by-ids` request. Matches
@@ -16,6 +16,13 @@ const SERVICE_ASSET_METADATA_CHUNK_SIZE = 100;
  * {@link SERVICE_ASSET_METADATA_CHUNK_SIZE} for the forward id lookup.
  */
 const SERVICE_ASSET_METADATA_BY_SHA_CHUNK_SIZE = 100;
+/**
+ * Maximum number of ids sent per `POST /assets/service/linked-url` request.
+ * Matches that route's own cap, which is a QUARTER of the metadata routes' —
+ * see `MAX_ASSETS_LINKED_URL` in the API for why minting download credentials is
+ * budgeted more tightly than projecting rows.
+ */
+const SERVICE_LINKED_DOWNLOAD_URL_CHUNK_SIZE = 25;
 /**
  * Lowercase hex SHA-256 digest matcher (exactly 64 hex chars). The reverse
  * lookup drops non-conforming hashes client-side so a single malformed value
@@ -358,6 +365,89 @@ export function OxyServicesAssetsMixin(Base) {
             }
             return settled.flat();
         }
+        /**
+         * Mint short-lived direct download URLs for files the calling application's
+         * own users attached to it, via `POST /assets/service/linked-url`.
+         *
+         * This is the ONLY path in this SDK by which a service token reaches file
+         * BYTES. {@link getServiceAssetMetadataByIds} is metadata-only, and every
+         * other download helper here — {@link getFileDownloadUrl},
+         * {@link getFileDownloadUrlAsync}, {@link getBatchFileAccess} — resolves a URL
+         * for the CURRENT USER through `makeRequest`, which is a different question: a
+         * relying service holds no user session, and the buyer whose entitlement it is
+         * enforcing is not a viewer Oxy knows anything about.
+         *
+         * **Service-token auth (required), plus the `files:linked:read` scope**, which
+         * is NOT implied by `files:read`. The calling client must be service-configured
+         * (`configureServiceAuth(apiKey, apiSecret)`); a user-session request is
+         * rejected by the route's service-auth guard.
+         *
+         * **What the server will and will not give you.** A URL comes back only for a
+         * file whose OWN OWNER linked it to this application (`file_links.created_by =
+         * files.owner_user_id`). Every other id is omitted: unknown, deleted,
+         * system-owned, linked by somebody else, or not linked here at all. So the
+         * result is routinely shorter than the input and must be mapped by `id`.
+         *
+         * ABSENCE IS A REFUSAL, NOT A FACT ABOUT THE FILE, and the caller is the only
+         * party that can tell the difference. The route deliberately cannot — it
+         * answers identically for "no such file" and "not yours" so it leaks nothing —
+         * which means a service must decide what to tell its user from its OWN
+         * entitlement record, never from this response. Do not surface "file not
+         * found" on the strength of an omission.
+         *
+         * FAILURE IS NOT ABSENCE EITHER, and here it cannot be opted out of: a failed
+         * chunk throws {@link ServiceLinkedDownloadUrlError} carrying its ids, with no
+         * `{ partial: true }` mode. Swallowing a 429 would tell a user who paid for a
+         * file that it is not there. An empty input resolves to `[]` with no network
+         * call.
+         *
+         * Never cached at the SDK layer, and that is a stronger statement than the
+         * sibling methods' "low hit rate": each entry is a live credential for the
+         * bytes, so caching one keeps it usable after the service has decided the
+         * caller's entitlement ended.
+         */
+        async getServiceLinkedDownloadUrls(ids) {
+            const uniqueIds = Array.from(new Set(ids.filter((id) => typeof id === 'string' && id.trim().length > 0)));
+            if (uniqueIds.length === 0) {
+                return [];
+            }
+            const chunks = [];
+            for (let i = 0; i < uniqueIds.length; i += SERVICE_LINKED_DOWNLOAD_URL_CHUNK_SIZE) {
+                chunks.push(uniqueIds.slice(i, i + SERVICE_LINKED_DOWNLOAD_URL_CHUNK_SIZE));
+            }
+            // Chunks stay independent so one failure never cancels work already in
+            // flight; the failures are collected and re-raised together below, exactly
+            // as in the metadata sibling.
+            const unresolvedIds = [];
+            const statuses = [];
+            let firstError;
+            const settled = await Promise.all(chunks.map(async (chunk) => {
+                try {
+                    const entries = await this.makeServiceRequest('POST', '/assets/service/linked-url', { ids: chunk });
+                    return Array.isArray(entries) ? entries : [];
+                }
+                catch (error) {
+                    const status = extractErrorStatus(error);
+                    // `chunkSize` and `status`, never the ids and never a `url`: a minted
+                    // URL in a log line is a credential in a log line.
+                    logger.warn('getServiceLinkedDownloadUrls: chunk failed', {
+                        method: 'getServiceLinkedDownloadUrls',
+                        chunkSize: chunk.length,
+                        status,
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                    unresolvedIds.push(...chunk);
+                    if (typeof status === 'number')
+                        statuses.push(status);
+                    firstError ?? (firstError = error);
+                    return [];
+                }
+            }));
+            if (unresolvedIds.length > 0) {
+                throw new ServiceLinkedDownloadUrlError(unresolvedIds, statuses, firstError);
+            }
+            return settled.flat();
+        }
         /**
          * Reverse content-address lookup: resolve many content `sha256` digests to
          * the servable Oxy asset holding each, in one round-trip per chunk via

package/dist/esm/mixins/OxyServices.connectedApps.js

@@ -1,9 +1,6 @@
 import { CACHE_TIMES } from './mixinHelpers.js';
 export function OxyServicesConnectedAppsMixin(Base) {
     return class extends Base {
-        constructor(...args) {
-            super(...args);
-        }
         /**
          * Resolve an OAuth client identifier to the owning application's PUBLIC
          * identity. No authentication required — the API returns only sanitized,
@@ -71,5 +68,25 @@ export function OxyServicesConnectedAppsMixin(Base) {
                 throw this.handleError(error);
             }
         }
+        /** List resource-bound external MCP connections for the active Oxy account. */
+        async listConnectedMcpClients() {
+            try {
+                const response = await this.makeRequest('GET', '/auth/mcp/oauth/grants', undefined, { cache: true, cacheTTL: CACHE_TIMES.SHORT });
+                return response.grants;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /** Revoke one external MCP connection and every token in its family. */
+        async revokeConnectedMcpClient(grantId) {
+            try {
+                await this.makeRequest('DELETE', `/auth/mcp/oauth/grants/${encodeURIComponent(grantId)}`, undefined, { cache: false });
+                this.clearCacheEntry('GET:/auth/mcp/oauth/grants');
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
     };
 }

package/dist/esm/mixins/OxyServices.utility.js

@@ -1,12 +1,10 @@
 /**
  * Utility Methods Mixin
  *
- * Provides utility methods including link metadata fetching
- * and Express.js authentication middleware
+ * Provides utility methods including Express.js authentication middleware.
  */
 import { jwtDecode } from 'jwt-decode';
 import { loadNodeCrypto } from '@oxy.so/protocol';
-import { buildUrl } from '../utils/apiUtils.js';
 import { logger } from '../logger/index.js';
 import { OXY_SERVICE_ENVIRONMENTS } from '../utils/oxyServiceEnvironment.js';
 /**
@@ -135,24 +133,6 @@ export function OxyServicesUtilityMixin(Base) {
                 return null;
             }
         }
-        /**
-         * Fetch link metadata
-         */
-        async fetchLinkMetadata(url) {
-            try {
-                const path = buildUrl('/links/preview', { url, wait: 1 });
-                const preview = await this.makeRequest('GET', path, undefined, { cache: false });
-                return {
-                    url: preview.url,
-                    title: preview.title?.trim() || preview.url.replace(/^https?:\/\//, '').replace(/\/$/, ''),
-                    description: preview.description?.trim() || 'Link',
-                    image: preview.image,
-                };
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
         /**
          * Express.js authentication middleware
          *

package/dist/esm/mixins/index.js

@@ -16,6 +16,7 @@ import { OxyServicesReputationMixin } from './OxyServices.reputation.js';
 import { OxyServicesAssetsMixin } from './OxyServices.assets.js';
 import { OxyServicesAccountsMixin } from './OxyServices.accounts.js';
 import { OxyServicesConnectedAppsMixin } from './OxyServices.connectedApps.js';
+import { OxyServicesAgencyMixin } from './OxyServices.agency.js';
 import { OxyServicesStoreMixin } from './OxyServices.store.js';
 import { OxyServicesLocationMixin } from './OxyServices.location.js';
 import { OxyServicesAnalyticsMixin } from './OxyServices.analytics.js';
@@ -30,7 +31,6 @@ import { OxyServicesAppDataMixin } from './OxyServices.appData.js';
 import { OxyServicesCivicMixin } from './OxyServices.civic.js';
 import { OxyServicesChainsMixin } from './OxyServices.chains.js';
 import { OxyServicesNodesMixin } from './OxyServices.nodes.js';
-import { OxyServicesLinksMixin } from './OxyServices.links.js';
 import { OxyServicesFollowGraphMixin } from './OxyServices.followGraph.js';
 import { OxyServicesInferenceMixin } from './OxyServices.inference.js';
 import { OxyServicesDeviceBootMixin } from './OxyServices.deviceBoot.js';
@@ -69,6 +69,8 @@ const MIXIN_PIPELINE = [
     // OAuth-consent surface (public app identity + connected-app grants). Kept
     // separate from account ownership.
     OxyServicesConnectedAppsMixin,
+    // Oxy-owned delegated authority for Alia and digital-agent accounts.
+    OxyServicesAgencyMixin,
     // The app store: the public storefront, the reviews on it, and the listing a
     // publisher edits. A module OVER the platform — turn it off and OAuth still
     // works — so it is its own surface rather than more of `accounts`.
@@ -91,9 +93,6 @@ const MIXIN_PIPELINE = [
     // User nodes / decentralization (Fase 5): register/read/revoke/manage the
     // caller's personal data node + ingest hint.
     OxyServicesNodesMixin,
-    // Link previews / unfurls: SDK-owned link-metadata resolution via oxy-api,
-    // so apps stop scraping link metadata locally.
-    OxyServicesLinksMixin,
     // The user-owned follow graph (#809). One relationship per user and target,
     // shared across applications, with per-application context on top.
     OxyServicesFollowGraphMixin,

package/dist/esm/server/index.js

@@ -45,3 +45,5 @@ export { evictOxyIdentityCache, oxyUserByIdCacheKey, OXY_IDENTITY_CACHE_PREFIXES
 // lets `@oxy.so/api` derive `auth.<apex>` without duplicating PSL logic.
 export { registrableApex } from '../utils/registrableApex.js';
 export { isOfficialWebOrigin } from '../utils/officialOrigins.js';
+export { createEcosystemTraffic } from './traffic.js';
+export { observeNodeHttp, withoutNodeHttpObservation } from './trafficNodeHttp.js';

package/dist/esm/server/traffic.js

@@ -0,0 +1,104 @@
+import { observeNodeHttp, withoutNodeHttpObservation } from './trafficNodeHttp.js';
+import { observeTrafficSocket, observeTrafficWebSocket } from '@oxy.so/telemetry/socket';
+import { randomUUID } from 'node:crypto';
+import { OxyServices } from '../OxyServices.js';
+import { createTrafficCollector, instrumentTrafficFetch, trafficMiddleware, resolveOxyServiceEndpoint, infrastructureLocation } from '@oxy.so/telemetry/collector';
+/** Install once per service process, before registering HTTP routes. */
+export function createEcosystemTraffic(options) {
+    const region = options.region ?? process.env.AWS_REGION ?? 'unknown';
+    const baseURL = options.baseURL ?? process.env.OXY_API_URL ?? 'https://api.oxy.so';
+    const activityKey = process.env.OXY_ACTIVITY_API_KEY;
+    const activitySecret = process.env.OXY_ACTIVITY_API_SECRET;
+    if (!options.credential && Boolean(activityKey) !== Boolean(activitySecret)) {
+        throw new Error('Ecosystem activity requires a complete OXY_ACTIVITY_API_KEY and OXY_ACTIVITY_API_SECRET pair');
+    }
+    const apiKey = activityKey || process.env.OXY_SERVICE_API_KEY;
+    const apiSecret = activitySecret || process.env.OXY_SERVICE_API_SECRET;
+    if (!options.credential && (!apiKey || !apiSecret))
+        throw new Error('Ecosystem activity requires OXY_SERVICE_API_KEY and OXY_SERVICE_API_SECRET');
+    const oxy = new OxyServices({ baseURL });
+    if (apiKey && apiSecret)
+        oxy.configureServiceAuth(apiKey, apiSecret);
+    const credential = options.credential ?? (() => oxy.getServiceToken());
+    const fetcher = globalThis.fetch.bind(globalThis);
+    const instanceId = randomUUID();
+    const location = options.location ?? infrastructureLocation(region);
+    if (!location)
+        throw new Error('Ecosystem activity requires a known infrastructure region or explicit location');
+    const post = async (path, data) => {
+        const token = await credential();
+        const response = await fetcher(new URL(path, baseURL), {
+            method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+            body: JSON.stringify(data), signal: AbortSignal.timeout(4000),
+        });
+        if (!response.ok)
+            throw new Error('Activity collection failed');
+    };
+    const collector = createTrafficCollector(events => post('/internal/activity', events));
+    let stopped = false;
+    let heartbeatWork = Promise.resolve();
+    let heartbeatPending = false;
+    const reportError = options.onError ?? (() => console.warn('Ecosystem activity publisher unavailable'));
+    const heartbeat = (removed = false) => {
+        if (!removed && (stopped || heartbeatPending))
+            return heartbeatWork;
+        heartbeatPending = true;
+        heartbeatWork = heartbeatWork.then(() => post('/internal/activity/infrastructure', { instanceId, service: options.service, region, ...location, status: options.ready?.() ? 'online' : 'unknown', removed })).catch(reportError).finally(() => { heartbeatPending = false; });
+        return heartbeatWork;
+    };
+    const flush = () => collector.flush().catch(reportError);
+    const cleanups = new Set();
+    const sockets = new WeakMap();
+    let fetchInstalled = false;
+    const wrapFetch = (fetcher) => {
+        const wrapped = instrumentTrafficFetch(fetcher, collector, options.service, region, options.resolveEndpoint ?? resolveOxyServiceEndpoint);
+        return Object.assign((...args) => withoutNodeHttpObservation(() => wrapped(...args)), fetcher);
+    };
+    const observeHttp = trafficMiddleware(collector, options.service, region);
+    const timer = setInterval(() => { void flush(); }, 2000);
+    timer.unref?.();
+    void heartbeat();
+    const heartbeatTimer = setInterval(() => { void heartbeat(); }, 10000);
+    heartbeatTimer.unref?.();
+    return {
+        record: flow => collector.record({ ...flow, service: options.service, region }),
+        middleware: observeHttp,
+        observeHttp,
+        wrapFetch,
+        installFetch() {
+            if (fetchInstalled || stopped)
+                return;
+            fetchInstalled = true;
+            const original = globalThis.fetch;
+            const wrapped = wrapFetch(original);
+            globalThis.fetch = wrapped;
+            cleanups.add(() => { if (globalThis.fetch === wrapped)
+                globalThis.fetch = original; });
+            cleanups.add(observeNodeHttp(collector, options.service, region, options.resolveEndpoint ?? resolveOxyServiceEndpoint));
+        },
+        observeWebSocket(socket, socketOptions) {
+            const existing = sockets.get(socket);
+            if (existing)
+                return existing;
+            const unobserve = observeTrafficWebSocket(socket, collector, options.service, region, socketOptions);
+            const cleanup = () => { unobserve(); socket.off('close', cleanup); cleanups.delete(cleanup); sockets.delete(socket); };
+            sockets.set(socket, cleanup);
+            socket.once('close', cleanup);
+            cleanups.add(cleanup);
+            return cleanup;
+        },
+        observeSocket(socket, socketOptions) {
+            const existing = sockets.get(socket);
+            if (existing)
+                return existing;
+            const unobserve = observeTrafficSocket(socket, collector, options.service, region, socketOptions);
+            const cleanup = () => { unobserve(); socket.off('disconnect', cleanup); cleanups.delete(cleanup); sockets.delete(socket); };
+            sockets.set(socket, cleanup);
+            socket.once('disconnect', cleanup);
+            cleanups.add(cleanup);
+            return cleanup;
+        },
+        async stop() { if (stopped)
+            return; stopped = true; cleanups.forEach(cleanup => cleanup()); cleanups.clear(); clearInterval(timer); clearInterval(heartbeatTimer); await flush(); await heartbeat(true); },
+    };
+}