@oxy.so/core 1.0.1 → 1.1.2

package/dist/types/OxyServices.errors.d.ts

@@ -79,6 +79,30 @@ export declare class ServiceAssetMetadataError extends Error {
     readonly cause?: unknown;
     constructor(unresolvedIds: string[], statuses: number[], cause?: unknown);
 }
+/**
+ * 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 declare class ServiceLinkedDownloadUrlError extends Error {
+    readonly code = "SERVICE_LINKED_DOWNLOAD_URL_UNRESOLVED";
+    /** Every id belonging to a chunk whose request failed. */
+    readonly unresolvedIds: string[];
+    /** HTTP statuses observed across the failed chunks (deduped, ascending). */
+    readonly statuses: number[];
+    /** The first underlying transport/API failure — see the sibling class. */
+    readonly cause?: unknown;
+    constructor(unresolvedIds: string[], statuses: number[], cause?: unknown);
+}
 export declare class OxyAuthenticationTimeoutError extends OxyAuthenticationError {
     constructor(operationName: string, timeoutMs: number);
 }

package/dist/types/index.d.ts

@@ -38,7 +38,8 @@ export { getCanonicalUserHandle, getNormalizedUserHandle, } from './utils/userHa
 export type { CanonicalUserHandleInput, UserHandleInput } from './utils/userHandle';
 export { normalizeProfileLinks } from './utils/profileLinks';
 export type { ProfileLink, ProfileLinkMetadata } from './utils/profileLinks';
-export type { PublicApplication, ConnectedApp, } from './mixins/OxyServices.connectedApps';
+export type { PublicApplication, ConnectedApp, ConnectedMcpClient, } from './mixins/OxyServices.connectedApps';
+export type { AccountCapabilityPolicy, AvailableCapabilityCatalog, CapabilityExecutionAuthorization, CreateDelegationGrantInput, DelegationCatalogBinding, DelegationGrantView, PutAccountCapabilityPolicyInput, UpdateDelegationGrantInput, } from './mixins/OxyServices.agency';
 export type { StoreCategory, StoreRating, StoreListingSummary, StoreListingDetail, StoreScreenshot, StoreScreenshotPlatform, StoreReview, StoreOwnReview, WriteStoreReviewInput, StoreListingStatus, PublisherListing, WriteListingInput, AddScreenshotInput, UpdateScreenshotInput, StorePage, StorePageOptions, StoreReviewsOptions, } from './mixins/OxyServices.store';
 export type { AccountKind, AccountCategoryId, AccountRelationship, AccountRole, AccountMemberStatus, AccountMemberSource, AccountMember, AccountNode, ListAccountsOptions, CreateAccountInput, UpdateAccountInput, ProvisionChannelInput, ProvisionChannelMemberInput, ProvisionChannelResult, InviteAccountMemberInput, UpdateAccountMemberInput, TransferAccountOwnershipInput, AccountSuccessResult, SwitchAccountResult, Application, ApplicationType, ApplicationStatus, ApplicationCredential, ApplicationCredentialType, ApplicationCredentialStatus, ApplicationEnvironment, CreateApplicationInput, UpdateApplicationInput, CreateApplicationCredentialInput, RotateApplicationCredentialInput, ApplicationCredentialWithSecret, RotateApplicationCredentialResult, ApplicationUsagePeriod, ApplicationUsageSummary, ApplicationUsageByDay, ApplicationUsageByEndpoint, ApplicationUsageStats, } from './mixins/OxyServices.accounts';
 export { ACCOUNT_CATEGORY_IDS, MAX_ACCOUNT_CATEGORIES, SELECTABLE_ACCOUNT_CATEGORY_IDS, isSelectableAccountCategoryId, kindAcceptsAccountCategories, } from './mixins/OxyServices.accounts';

package/dist/types/mixins/OxyServices.agency.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Native Alia and digital-agent authority.
+ *
+ * These methods manage Oxy-owned delegation grants, account autonomy policy,
+ * execution authorizations and their audit trail. They deliberately use the
+ * signed-in account session: capability tickets and app service credentials
+ * stay on the server and are never exposed to Settings clients.
+ */
+import type { AppCapabilityCatalog, AuditEvent, AutonomyLevel, CapabilityCatalogBinding, CapabilityPackage, DelegationGrant, GrantLimit, ResourceRef, ToolGrantOverride } from '@oxy.so/contracts';
+import type { OxyServicesBase } from '../OxyServices.base';
+export type DelegationCatalogBinding = CapabilityCatalogBinding;
+export type DelegationGrantView = DelegationGrant;
+export interface CreateDelegationGrantInput {
+    ownerAccountId: string;
+    actorAccountId: string;
+    resource: ResourceRef;
+    capabilityPackages: CapabilityPackage[];
+    capabilities: string[];
+    toolOverrides?: ToolGrantOverride[];
+    limits?: GrantLimit[];
+    maximumAutonomy: AutonomyLevel;
+    canRedelegate?: boolean;
+    expiresAt?: string | null;
+}
+export type UpdateDelegationGrantInput = Pick<CreateDelegationGrantInput, 'capabilityPackages' | 'capabilities' | 'toolOverrides' | 'limits' | 'maximumAutonomy' | 'canRedelegate' | 'expiresAt'>;
+export interface AvailableCapabilityCatalog {
+    id: string;
+    appId: string;
+    version: string;
+    digest: string;
+    audience: string;
+    catalog: AppCapabilityCatalog;
+}
+export interface AccountCapabilityPolicy {
+    id: string;
+    accountId: string;
+    appSlug: string;
+    maximumAutonomy: AutonomyLevel;
+    deniedCapabilities: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+export interface PutAccountCapabilityPolicyInput {
+    accountId: string;
+    maximumAutonomy: AutonomyLevel;
+    deniedCapabilities: string[];
+}
+export interface CapabilityExecutionAuthorization {
+    id: string;
+    kind: 'direct_request' | 'automation';
+    requesterAccountId: string;
+    ownerAccountId: string;
+    coordinatorApplicationId: string;
+    coordinatorCredentialId: string;
+    actorType: 'alia' | 'agent';
+    actorAccountId: string | null;
+    resourceApp: string;
+    effectiveAccountId: string;
+    resourceType: string;
+    resourceKey: string;
+    tool: string;
+    runId: string | null;
+    stepId: string | null;
+    automationId: string | null;
+    maximumAutonomy: AutonomyLevel;
+    limits: GrantLimit[];
+    expiresAt: string;
+    revokedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export declare function OxyServicesAgencyMixin<T extends typeof OxyServicesBase>(Base: T): {
+    new (...args: any[]): {
+        listAvailableCapabilityCatalogs(accountId: string): Promise<AvailableCapabilityCatalog[]>;
+        listDelegationGrants(ownerAccountId: string): Promise<DelegationGrantView[]>;
+        createDelegationGrant(input: CreateDelegationGrantInput): Promise<DelegationGrantView>;
+        revokeDelegationGrant(grantId: string, ownerAccountId: string): Promise<void>;
+        updateDelegationGrant(grantId: string, ownerAccountId: string, input: UpdateDelegationGrantInput): Promise<DelegationGrantView>;
+        listAccountCapabilityPolicies(accountId: string): Promise<AccountCapabilityPolicy[]>;
+        putAccountCapabilityPolicy(appId: string, input: PutAccountCapabilityPolicyInput): Promise<AccountCapabilityPolicy>;
+        deleteAccountCapabilityPolicy(appId: string, accountId: string): Promise<void>;
+        listCapabilityExecutionAuthorizations(ownerAccountId: string): Promise<CapabilityExecutionAuthorization[]>;
+        revokeCapabilityExecutionAuthorization(authorizationId: string, ownerAccountId: string): Promise<void>;
+        listCapabilityAuditEvents(accountId: string): Promise<AuditEvent[]>;
+        httpService: import("../HttpService").HttpService;
+        cloudURL: string;
+        config: import("../OxyServices.base").OxyConfig;
+        __resetTokensForTests(): void;
+        makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
+        getBaseURL(): string;
+        getClient(): import("../HttpService").HttpService;
+        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
+        getMetrics(): {
+            totalRequests: number;
+            successfulRequests: number;
+            failedRequests: number;
+            cacheHits: number;
+            cacheMisses: number;
+            averageResponseTime: number;
+        };
+        clearCache(): void;
+        clearCacheEntry(key: string): void;
+        clearCacheByPrefix(prefix: string): number;
+        getCacheStats(): {
+            size: number;
+            hits: number;
+            misses: number;
+            hitRate: number;
+        };
+        getCloudURL(): string;
+        setTokens(accessToken: string): void;
+        clearTokens(): void;
+        onTokensChanged(listener: (accessToken: string | null) => void): () => void;
+        _cachedUserId: string | null | undefined;
+        _cachedAccessToken: string | null;
+        getCurrentUserId(): string | null;
+        hasValidToken(): boolean;
+        getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | null;
+        waitForAuth(timeoutMs?: number): Promise<boolean>;
+        withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {
+            maxRetries?: number;
+            retryDelay?: number;
+            authTimeoutMs?: number;
+        }): Promise<T_1>;
+        validate(): Promise<boolean>;
+        handleError(error: unknown): Error;
+        healthCheck(): Promise<{
+            status: string;
+            users?: number;
+            timestamp?: string;
+            [key: string]: any;
+        }>;
+    };
+} & T;

package/dist/types/mixins/OxyServices.assets.d.ts

@@ -1,4 +1,4 @@
-import type { AccountStorageUsageResponse, AssetUploadInput, AssetUrlResponse, AssetVariant, BatchFileAccessResponse, ServiceAssetMetadata, ServiceAssetMetadataBySha } from '../models/interfaces';
+import type { AccountStorageUsageResponse, AssetUploadInput, AssetUrlResponse, AssetVariant, BatchFileAccessResponse, ServiceAssetMetadata, ServiceAssetMetadataBySha, ServiceLinkedDownloadUrl } from '../models/interfaces';
 import type { OxyServicesBase } from '../OxyServices.base';
 export declare function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T): {
     new (...args: any[]): {
@@ -181,6 +181,48 @@ export declare function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>
         getServiceAssetMetadataByIds(ids: string[], options?: {
             partial?: boolean;
         }): Promise<ServiceAssetMetadata[]>;
+        /**
+         * 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.
+         */
+        getServiceLinkedDownloadUrls(ids: string[]): Promise<ServiceLinkedDownloadUrl[]>;
         /**
          * 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/types/mixins/OxyServices.connectedApps.d.ts

@@ -77,6 +77,17 @@ export interface ConnectedApp {
     /** ISO timestamp of when the grant was last exercised. */
     lastUsedAt: string;
 }
+/** An external MCP client authorized for one exact app resource and account. */
+export interface ConnectedMcpClient {
+    id: string;
+    appSlug: string;
+    resource: string;
+    scopes: string[];
+    clientId: string;
+    clientName: string;
+    createdAt: string;
+    lastUsedAt: string;
+}
 export declare function OxyServicesConnectedAppsMixin<T extends typeof OxyServicesBase>(Base: T): {
     new (...args: any[]): {
         /**
@@ -116,6 +127,10 @@ export declare function OxyServicesConnectedAppsMixin<T extends typeof OxyServic
          * @param applicationId - The connected application's Mongo `_id`.
          */
         revokeAppGrant(applicationId: string): Promise<void>;
+        /** List resource-bound external MCP connections for the active Oxy account. */
+        listConnectedMcpClients(): Promise<ConnectedMcpClient[]>;
+        /** Revoke one external MCP connection and every token in its family. */
+        revokeConnectedMcpClient(grantId: string): Promise<void>;
         httpService: import("../HttpService").HttpService;
         cloudURL: string;
         config: import("../OxyServices.base").OxyConfig;

package/dist/types/mixins/OxyServices.utility.d.ts

@@ -121,15 +121,6 @@ export declare function OxyServicesUtilityMixin<T extends typeof OxyServicesBase
          * @internal Used by the auth() middleware — not part of the public API
          */
         verifyServiceActingAs(appId: string, userId: string): Promise<ServiceActingAsVerification | null>;
-        /**
-         * Fetch link metadata
-         */
-        fetchLinkMetadata(url: string): Promise<{
-            url: string;
-            title: string;
-            description: string;
-            image?: string;
-        }>;
         /**
          * Express.js authentication middleware
          *

package/dist/types/mixins/index.d.ts

@@ -16,6 +16,7 @@ import { OxyServicesReputationMixin } from './OxyServices.reputation';
 import { OxyServicesAssetsMixin } from './OxyServices.assets';
 import { OxyServicesAccountsMixin } from './OxyServices.accounts';
 import { OxyServicesConnectedAppsMixin } from './OxyServices.connectedApps';
+import { OxyServicesAgencyMixin } from './OxyServices.agency';
 import { OxyServicesStoreMixin } from './OxyServices.store';
 import { OxyServicesLocationMixin } from './OxyServices.location';
 import { OxyServicesAnalyticsMixin } from './OxyServices.analytics';
@@ -30,7 +31,6 @@ import { OxyServicesAppDataMixin } from './OxyServices.appData';
 import { OxyServicesCivicMixin } from './OxyServices.civic';
 import { OxyServicesChainsMixin } from './OxyServices.chains';
 import { OxyServicesNodesMixin } from './OxyServices.nodes';
-import { OxyServicesLinksMixin } from './OxyServices.links';
 import { OxyServicesFollowGraphMixin } from './OxyServices.followGraph';
 import { OxyServicesInferenceMixin } from './OxyServices.inference';
 import { OxyServicesDeviceBootMixin } from './OxyServices.deviceBoot';
@@ -44,7 +44,7 @@ import { OxyServicesDeviceTransferMixin } from './OxyServices.deviceTransfer';
  * If you add a new mixin to `MIXIN_PIPELINE`, add it here too so its methods
  * are visible without a cast.
  */
-type AllMixinInstances = InstanceType<ReturnType<typeof OxyServicesAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityBackupMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPrivacyMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLanguageMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPaymentMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesReputationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAccountsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesConnectedAppsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesStoreMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDevicesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSecurityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFeaturesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesTopicsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesNotificationsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesCivicMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesChainsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesNodesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLinksMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFollowGraphMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesInferenceMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeviceBootMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeviceTransferMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
+type AllMixinInstances = InstanceType<ReturnType<typeof OxyServicesAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityBackupMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPrivacyMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLanguageMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPaymentMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesReputationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAccountsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesConnectedAppsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAgencyMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesStoreMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDevicesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSecurityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFeaturesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesTopicsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesNotificationsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesCivicMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesChainsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesNodesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFollowGraphMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesInferenceMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeviceBootMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeviceTransferMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
 /**
  * Constructor type for the fully composed mixin pipeline. Each mixin returns
  * a new constructor that augments its input; reducing across the pipeline

package/dist/types/models/interfaces.d.ts

@@ -525,6 +525,32 @@ export interface AssetUpdateVisibilityResponse {
  * deleted ids are omitted from the response (never error the whole batch),
  * so the result may be shorter than the requested id list.
  */
+/**
+ * A short-lived direct download URL for a file the calling application's own
+ * user attached to it, from `POST /assets/service/linked-url`.
+ *
+ * `url` is BEARER AUTHORITY over the bytes for `expiresIn` seconds: whoever
+ * holds the string is the reader, and nothing about the calling service's
+ * entitlement is re-evaluated when it is used. Hand it only to a caller the
+ * service has itself authorized, and never log it.
+ *
+ * `expiresIn` bounds when a transfer may START, not how long one may take. A
+ * large file downloads fine on a slow link; a RESUMED range request after the
+ * deadline does not, and needs a fresh URL.
+ *
+ * Unlike {@link ServiceAssetMetadata}, the absence of an id from the response is
+ * an AUTHORIZATION answer as often as an existence one — see
+ * `getServiceLinkedDownloadUrls`.
+ */
+export interface ServiceLinkedDownloadUrl {
+    id: string;
+    url: string;
+    /** Seconds from issue until `url` stops being accepted. */
+    expiresIn: number;
+    mime: string;
+    size: number;
+    sha256: string;
+}
 export interface ServiceAssetMetadata {
     id: string;
     sha256: string;

package/dist/types/server/index.d.ts

@@ -33,3 +33,6 @@ export { evictOxyIdentityCache, oxyUserByIdCacheKey, OXY_IDENTITY_CACHE_PREFIXES
 export type { OxyIdentityCacheEvictor } from '../utils/identityCacheSweep';
 export { registrableApex } from '../utils/registrableApex';
 export { isOfficialWebOrigin } from '../utils/officialOrigins';
+export { createEcosystemTraffic } from './traffic';
+export type { EcosystemTrafficOptions } from './traffic';
+export { observeNodeHttp, withoutNodeHttpObservation } from './trafficNodeHttp';

package/dist/types/server/traffic.d.ts

@@ -0,0 +1,27 @@
+import { observeTrafficSocket, observeTrafficWebSocket, type TrafficWebSocket, type TrafficSocket } from '@oxy.so/telemetry/socket';
+import type { RequestHandler } from 'express';
+import { trafficMiddleware, type TrafficFlow, type ServiceEndpoint } from '@oxy.so/telemetry/collector';
+export interface EcosystemTrafficOptions {
+    service: string;
+    region?: string;
+    baseURL?: string;
+    credential?: () => Promise<string>;
+    resolveEndpoint?: (url: URL) => ServiceEndpoint | undefined;
+    onError?: () => void;
+    ready?: () => boolean;
+    location?: {
+        label: string;
+        coordinates: [number, number];
+    };
+}
+/** Install once per service process, before registering HTTP routes. */
+export declare function createEcosystemTraffic(options: EcosystemTrafficOptions): {
+    middleware: RequestHandler;
+    record(flow: Omit<TrafficFlow, 'service' | 'region'>): void;
+    wrapFetch(fetcher: typeof fetch): typeof fetch;
+    installFetch(): void;
+    observeHttp: ReturnType<typeof trafficMiddleware>;
+    observeSocket(socket: TrafficSocket, options?: Parameters<typeof observeTrafficSocket>[4]): () => void;
+    observeWebSocket(socket: TrafficWebSocket, options?: Parameters<typeof observeTrafficWebSocket>[4]): () => void;
+    stop(): Promise<void>;
+};

package/dist/types/server/trafficNodeHttp.d.ts

@@ -0,0 +1,6 @@
+import { type TrafficFlow, type ServiceEndpoint } from '@oxy.so/telemetry/collector';
+export declare function withoutNodeHttpObservation<T>(callback: () => T): T;
+/** Node and Bun share the HTTP facade; Bun does not emit Node's HTTP diagnostic channels. */
+export declare function observeNodeHttp(collector: {
+    record(flow: TrafficFlow): void;
+}, service: string, region: string, resolveEndpoint: (url: URL) => ServiceEndpoint | undefined): () => void;

package/dist/types/utils/cache.d.ts

@@ -118,10 +118,7 @@ export declare function createCache<T>(ttl?: number): TTLCache<T>;
  * @param cache Cache instance to register
  */
 export declare function registerCacheForCleanup(cache: TTLCache<any>): void;
-/**
- * Unregister a cache from automatic cleanup
- * @param cache Cache instance to unregister
- */
+/** Unregister a cache without changing its entries or TTL behavior. */
 export declare function unregisterCacheFromCleanup(cache: TTLCache<any>): void;
 /**
  * Stop all cleanup intervals (useful for testing)

package/dist/types/utils/textNormalization.d.ts

@@ -43,7 +43,7 @@
  * normalize whitespace and Unicode form.
  */
 /**
- * Normalize a SINGLE-LINE text value: page/link-preview titles, `siteName`,
+ * Normalize a SINGLE-LINE text value such as a page title or `siteName`,
  * display names, image alt text, handles, profile field labels.
  *
  * A line break in such a value is never meaningful — it is an artifact of the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/core",
-  "version": "1.0.1",
+  "version": "1.1.2",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -86,7 +86,7 @@
     "node": ">=18.0.0"
   },
   "scripts": {
-    "build": "bun run build:cjs && bun run build:esm && bun run build:types && bun run copy-assets && node scripts/mark-module-formats.mjs",
+    "build": "bun run --filter @oxy.so/telemetry build && bun run build:cjs && bun run build:esm && bun run build:types && bun run copy-assets && node scripts/mark-module-formats.mjs",
     "copy-assets": "cp -r src/i18n/locales dist/cjs/i18n/locales && cp -r src/i18n/locales dist/esm/i18n/locales",
     "build:cjs": "tsc -p tsconfig.cjs.json",
     "build:esm": "tsc -p tsconfig.esm.json && node scripts/fix-esm-imports.mjs",
@@ -115,10 +115,10 @@
     }
   },
   "dependencies": {
-    "@oxy.so/telemetry": "^1.0.0",
+    "@oxy.so/telemetry": "^1.1.1",
     "@noble/ciphers": "^1.3.0",
     "@noble/hashes": "^1.8.0",
-    "@oxy.so/contracts": "^1.0.1",
+    "@oxy.so/contracts": "^1.1.1",
     "@oxy.so/protocol": "^1.0.1",
     "@scure/bip39": "^1.6.0",
     "buffer": "^6.0.3",

package/src/OxyServices.errors.ts

@@ -109,6 +109,42 @@ export class ServiceAssetMetadataError extends Error {
   }
 }
 
+/**
+ * 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 {
+  public readonly code = 'SERVICE_LINKED_DOWNLOAD_URL_UNRESOLVED';
+  /** Every id belonging to a chunk whose request failed. */
+  public readonly unresolvedIds: string[];
+  /** HTTP statuses observed across the failed chunks (deduped, ascending). */
+  public readonly statuses: number[];
+  /** The first underlying transport/API failure — see the sibling class. */
+  public readonly cause?: unknown;
+
+  constructor(unresolvedIds: string[], statuses: number[], cause?: unknown) {
+    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.name = 'ServiceLinkedDownloadUrlError';
+    this.unresolvedIds = unresolvedIds;
+    this.statuses = uniqueStatuses;
+    this.cause = cause;
+  }
+}
+
 export class OxyAuthenticationTimeoutError extends OxyAuthenticationError {
   constructor(operationName: string, timeoutMs: number) {
     super(

package/src/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/src/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/src/index.ts

@@ -122,8 +122,23 @@ export type { ProfileLink, ProfileLinkMetadata } from './utils/profileLinks';
 export type {
     PublicApplication,
     ConnectedApp,
+    ConnectedMcpClient,
 } from './mixins/OxyServices.connectedApps';
 
+// ---------------------------------------------------------------------------
+// Native Alia and digital-agent authority
+// ---------------------------------------------------------------------------
+export type {
+    AccountCapabilityPolicy,
+    AvailableCapabilityCatalog,
+    CapabilityExecutionAuthorization,
+    CreateDelegationGrantInput,
+    DelegationCatalogBinding,
+    DelegationGrantView,
+    PutAccountCapabilityPolicyInput,
+    UpdateDelegationGrantInput,
+} from './mixins/OxyServices.agency';
+
 // ---------------------------------------------------------------------------
 // App store (public storefront + reviews + the listing a publisher edits)
 // ---------------------------------------------------------------------------