fix(typespec-ts): simplify SDK User-Agent telemetry prefix

.chronus/changes/ts-simplify-user-agent-prefix-2026-7-2-14-30-0.md

@@ -0,0 +1,7 @@
+---
+changeKind: fix
+packages:
+  - "@azure-tools/typespec-ts"
+---
+
+Simplify the generated SDK `User-Agent` telemetry prefix to follow the [Azure Core telemetry policy](https://azure.github.io/azure-sdk/general_azurecore.html#telemetry-policy). The legacy internal layering tokens `azsdk-js-client` and `azsdk-js-api` are no longer emitted, so the user agent is now `[<application_id> ]azsdk-js-<package>/<version> <platform_info>`. Any caller-supplied application id is still forwarded and prepended.

packages/typespec-ts/src/modular/build-classical-client.ts

@@ -5,7 +5,7 @@ import {
   SourceFile,
   StructureKind,
 } from "ts-morph";
-import { buildUserAgentOptions, getClientParametersDeclaration } from "./helpers/client-helpers.js";
+import { getClientParametersDeclaration } from "./helpers/client-helpers.js";
 import { getClassicalClientName, getClientName } from "./helpers/naming-helpers.js";
 import { ModularEmitterOptions } from "./interfaces.js";
 
@@ -127,11 +127,7 @@ export function buildClassicalClient(
     .map((p) => p.name)
     .map((x) => {
       if (x === "options") {
-        return `{...options, userAgentOptions: ${buildUserAgentOptions(
-          constructor,
-          emitterOptions,
-          "azsdk-js-client",
-        )}}`;
+        return `options`;
       } else if (x.toLowerCase() === "subscriptionid" && shouldSubscriptionIdOptional) {
         return `subscriptionId ?? ""`;
       } else {

packages/typespec-ts/src/modular/helpers/client-helpers.ts

@@ -241,7 +241,7 @@ export function buildGetClientOptionsParam(
   endpointParam: string,
   apiVersionParamName?: string,
 ): string {
-  const userAgentOptions = buildUserAgentOptions(context, emitterOptions, "azsdk-js-api");
+  const userAgentOptions = buildUserAgentOptions(context, emitterOptions);
   const loggingOptions = buildLoggingOptions();
   const credentials = buildCredentials(emitterOptions, endpointParam);
 
@@ -313,10 +313,14 @@ function buildLoggingOptions(): string | undefined {
   return `{ logger: options.loggingOptions?.logger ?? logger.info }`;
 }
 
+/**
+ * Builds the `userAgentOptions` for the generated client, producing a telemetry
+ * prefix of the form `[<application_id> ]azsdk-js-<package>/<version>` per the Azure
+ * Core telemetry policy: https://azure.github.io/azure-sdk/general_azurecore.html#telemetry-policy
+ */
 export function buildUserAgentOptions(
   context: StatementedNode,
   emitterOptions: ModularEmitterOptions,
-  sdkUserAgentPrefix: string,
 ): string {
   const userAgentStatements = [];
   const prefixFromOptions = "const prefixFromOptions = options?.userAgentOptions?.userAgentPrefix;";
@@ -329,21 +333,20 @@ export function buildUserAgentOptions(
   const packageVersion = emitterOptions.options.packageDetails?.version ?? "";
 
   const userAgentInfoStatement =
-    packageVersion && clientPackageName && sdkUserAgentPrefix.includes("api")
+    packageVersion && clientPackageName
       ? "const userAgentInfo = `azsdk-js-" + clientPackageName + "/" + packageVersion + "`;"
       : "";
 
-  if (userAgentInfoStatement) {
-    userAgentStatements.push(userAgentInfoStatement);
+  if (!userAgentInfoStatement) {
+    // Without package name/version we cannot build a meaningful telemetry token,
+    // so we leave the user agent untouched (the caller's userAgentOptions still flow
+    // through `...options`) and let core-rest-pipeline defaults apply.
+    return "";
   }
-  const userAgentPrefix = `const userAgentPrefix = ${
-    "prefixFromOptions ? `${prefixFromOptions} " +
-    sdkUserAgentPrefix +
-    `${userAgentInfoStatement ? " ${userAgentInfo}" : ""}` +
-    "` : `" +
-    `${sdkUserAgentPrefix}` +
-    `${userAgentInfoStatement ? " ${userAgentInfo}`" : "`"}`
-  };`;
+
+  userAgentStatements.push(userAgentInfoStatement);
+  const userAgentPrefix =
+    "const userAgentPrefix = prefixFromOptions ? `${prefixFromOptions} ${userAgentInfo}` : `${userAgentInfo}`;";
   userAgentStatements.push(userAgentPrefix);
 
   context.addStatements(userAgentStatements.join("\n"));

packages/typespec-ts/test/azure-modular-integration/generated/routes/src/index.d.ts

@@ -4,6 +4,11 @@ import { OperationOptions } from '@azure-rest/core-client';
 import { Pipeline } from '@azure/core-rest-pipeline';
 import { RestError } from '@azure/core-rest-pipeline';
 
+export declare interface ExpandParameters {
+    field: string;
+    value: string;
+}
+
 export declare interface FixedOptionalParams extends OperationOptions {
 }
 
@@ -239,7 +244,11 @@ export declare interface QueryParametersQueryContinuationStandardRecordOptionalP
 export declare interface QueryParametersQueryExpansionExplodeArrayOptionalParams extends OperationOptions {
 }
 
+export declare interface QueryParametersQueryExpansionExplodeModelOptionalParams extends OperationOptions {
+}
+
 export declare interface QueryParametersQueryExpansionExplodeOperations {
+    model: (param: ExpandParameters, options?: QueryParametersQueryExpansionExplodeModelOptionalParams) => Promise<void>;
     record: (param: Record<string, number>, options?: QueryParametersQueryExpansionExplodeRecordOptionalParams) => Promise<void>;
     array: (param: string[], options?: QueryParametersQueryExpansionExplodeArrayOptionalParams) => Promise<void>;
     primitive: (param: string, options?: QueryParametersQueryExpansionExplodePrimitiveOptionalParams) => Promise<void>;

packages/typespec-ts/test/modular-unit/scenarios/api-operations/apiOperations.md

@@ -540,11 +540,8 @@ export function createTesting(
   options: TestingClientOptionalParams = {},
 ): TestingContext {
   const endpointUrl = options.endpoint ?? String(endpointParam);
-  const prefixFromOptions = options?.userAgentOptions?.userAgentPrefix;
-  const userAgentPrefix = prefixFromOptions ? `${prefixFromOptions} azsdk-js-api` : `azsdk-js-api`;
   const { apiVersion: _, ...updatedOptions } = {
     ...options,
-    userAgentOptions: { userAgentPrefix },
     loggingOptions: { logger: options.loggingOptions?.logger ?? logger.info },
   };
   const clientContext = getClient(endpointUrl, undefined, updatedOptions);
@@ -573,14 +570,7 @@ export class TestingClient {
   public readonly pipeline: Pipeline;
 
   constructor(endpointParam: string, options: TestingClientOptionalParams = {}) {
-    const prefixFromOptions = options?.userAgentOptions?.userAgentPrefix;
-    const userAgentPrefix = prefixFromOptions
-      ? `${prefixFromOptions} azsdk-js-client`
-      : `azsdk-js-client`;
-    this._client = createTesting(endpointParam, {
-      ...options,
-      userAgentOptions: { userAgentPrefix },
-    });
+    this._client = createTesting(endpointParam, options);
     this.pipeline = this._client.pipeline;
   }
 
@@ -678,11 +668,8 @@ export function createTesting(
   options: TestingClientOptionalParams = {},
 ): TestingContext {
   const endpointUrl = options.endpoint ?? String(endpointParam);
-  const prefixFromOptions = options?.userAgentOptions?.userAgentPrefix;
-  const userAgentPrefix = prefixFromOptions ? `${prefixFromOptions} azsdk-js-api` : `azsdk-js-api`;
   const { apiVersion: _, ...updatedOptions } = {
     ...options,
-    userAgentOptions: { userAgentPrefix },
     loggingOptions: { logger: options.loggingOptions?.logger ?? logger.info },
   };
   const clientContext = getClient(endpointUrl, undefined, updatedOptions);
@@ -711,14 +698,7 @@ export class TestingClient {
   public readonly pipeline: Pipeline;
 
   constructor(endpointParam: string, options: TestingClientOptionalParams = {}) {
-    const prefixFromOptions = options?.userAgentOptions?.userAgentPrefix;
-    const userAgentPrefix = prefixFromOptions
-      ? `${prefixFromOptions} azsdk-js-client`
-      : `azsdk-js-client`;
-    this._client = createTesting(endpointParam, {
-      ...options,
-      userAgentOptions: { userAgentPrefix },
-    });
+    this._client = createTesting(endpointParam, options);
     this.pipeline = this._client.pipeline;
   }
 
@@ -836,11 +816,8 @@ export function createTesting(
   options: TestingClientOptionalParams = {},
 ): TestingContext {
   const endpointUrl = options.endpoint ?? String(endpointParam);
-  const prefixFromOptions = options?.userAgentOptions?.userAgentPrefix;
-  const userAgentPrefix = prefixFromOptions ? `${prefixFromOptions} azsdk-js-api` : `azsdk-js-api`;
   const { apiVersion: _, ...updatedOptions } = {
     ...options,
-    userAgentOptions: { userAgentPrefix },
     loggingOptions: { logger: options.loggingOptions?.logger ?? logger.info },
   };
   const clientContext = getClient(endpointUrl, undefined, updatedOptions);
@@ -869,14 +846,7 @@ export class TestingClient {
   public readonly pipeline: Pipeline;
 
   constructor(endpointParam: string, options: TestingClientOptionalParams = {}) {
-    const prefixFromOptions = options?.userAgentOptions?.userAgentPrefix;
-    const userAgentPrefix = prefixFromOptions
-      ? `${prefixFromOptions} azsdk-js-client`
-      : `azsdk-js-client`;
-    this._client = createTesting(endpointParam, {
-      ...options,
-      userAgentOptions: { userAgentPrefix },
-    });
+    this._client = createTesting(endpointParam, options);
     this.pipeline = this._client.pipeline;
   }
 

packages/typespec-ts/test/modular-unit/scenarios/classic-client/classicClient.md

@@ -50,14 +50,7 @@ export class TestServiceClient {
   public readonly pipeline: Pipeline;
 
   constructor(endpointParam: string, options: TestServiceClientOptionalParams = {}) {
-    const prefixFromOptions = options?.userAgentOptions?.userAgentPrefix;
-    const userAgentPrefix = prefixFromOptions
-      ? `${prefixFromOptions} azsdk-js-client`
-      : `azsdk-js-client`;
-    this._client = createTestService(endpointParam, {
-      ...options,
-      userAgentOptions: { userAgentPrefix },
-    });
+    this._client = createTestService(endpointParam, options);
     this.pipeline = this._client.pipeline;
   }
 

packages/typespec-ts/test/modular-unit/scenarios/classic-client/clientConstructorOverloads.md

@@ -53,14 +53,7 @@ export class GlobalServiceClient {
 
   /** Client.GlobalService Resource Provider management API. */
   constructor(credential: TokenCredential, options: GlobalServiceClientOptionalParams = {}) {
-    const prefixFromOptions = options?.userAgentOptions?.userAgentPrefix;
-    const userAgentPrefix = prefixFromOptions
-      ? `${prefixFromOptions} azsdk-js-client`
-      : `azsdk-js-client`;
-    this._client = createGlobalService(credential, {
-      ...options,
-      userAgentOptions: { userAgentPrefix },
-    });
+    this._client = createGlobalService(credential, options);
     this.pipeline = this._client.pipeline;
     this.operations = _getOperationsOperations(this._client);
   }
@@ -188,14 +181,7 @@ export class StandardServiceClient {
     subscriptionId: string,
     options: StandardServiceClientOptionalParams = {},
   ) {
-    const prefixFromOptions = options?.userAgentOptions?.userAgentPrefix;
-    const userAgentPrefix = prefixFromOptions
-      ? `${prefixFromOptions} azsdk-js-client`
-      : `azsdk-js-client`;
-    this._client = createStandardService(credential, subscriptionId, {
-      ...options,
-      userAgentOptions: { userAgentPrefix },
-    });
+    this._client = createStandardService(credential, subscriptionId, options);
     this.pipeline = this._client.pipeline;
   }
 
@@ -340,14 +326,7 @@ export class MixedServiceClient {
     }
 
     options = options ?? {};
-    const prefixFromOptions = options?.userAgentOptions?.userAgentPrefix;
-    const userAgentPrefix = prefixFromOptions
-      ? `${prefixFromOptions} azsdk-js-client`
-      : `azsdk-js-client`;
-    this._client = createMixedService(credential, subscriptionId ?? "", {
-      ...options,
-      userAgentOptions: { userAgentPrefix },
-    });
+    this._client = createMixedService(credential, subscriptionId ?? "", options);
     this.pipeline = this._client.pipeline;
   }
 

packages/typespec-ts/test/modular-unit/scenarios/classic-client/doNotNormalizeOperationGroup.md

@@ -45,14 +45,7 @@ export class RelayClient {
   public readonly pipeline: Pipeline;
 
   constructor(endpointParam: string, options: RelayClientOptionalParams = {}) {
-    const prefixFromOptions = options?.userAgentOptions?.userAgentPrefix;
-    const userAgentPrefix = prefixFromOptions
-      ? `${prefixFromOptions} azsdk-js-client`
-      : `azsdk-js-client`;
-    this._client = createRelay(endpointParam, {
-      ...options,
-      userAgentOptions: { userAgentPrefix },
-    });
+    this._client = createRelay(endpointParam, options);
     this.pipeline = this._client.pipeline;
     this.wCFRelays = _getwCFRelaysOperations(this._client);
   }

packages/typespec-ts/test/modular-unit/scenarios/classic-client/reservedWordOperations.md

@@ -21,14 +21,7 @@ export class TestingClient {
   public readonly pipeline: Pipeline;
 
   constructor(endpointParam: string, options: TestingClientOptionalParams = {}) {
-    const prefixFromOptions = options?.userAgentOptions?.userAgentPrefix;
-    const userAgentPrefix = prefixFromOptions
-      ? `${prefixFromOptions} azsdk-js-client`
-      : `azsdk-js-client`;
-    this._client = createTesting(endpointParam, {
-      ...options,
-      userAgentOptions: { userAgentPrefix },
-    });
+    this._client = createTesting(endpointParam, options);
     this.pipeline = this._client.pipeline;
   }
 

packages/typespec-ts/test/modular-unit/scenarios/client-context/clientContext.md

@@ -77,11 +77,8 @@ export function createService(
 ): ServiceContext {
   const clientParam = options.clientParam ?? "default";
   const endpointUrl = options.endpoint ?? `${endpointParam}/client/structure/${clientParam}`;
-  const prefixFromOptions = options?.userAgentOptions?.userAgentPrefix;
-  const userAgentPrefix = prefixFromOptions ? `${prefixFromOptions} azsdk-js-api` : `azsdk-js-api`;
   const { apiVersion: _, ...updatedOptions } = {
     ...options,
-    userAgentOptions: { userAgentPrefix },
     loggingOptions: { logger: options.loggingOptions?.logger ?? logger.info },
   };
   const clientContext = getClient(endpointUrl, undefined, updatedOptions);
@@ -174,11 +171,8 @@ export function createService(options: ServiceClientOptionalParams = {}): Servic
   const endpointParam = options.endpointParam ?? "http://localhost:3000";
   const clientParam = options.clientParam ?? "default";
   const endpointUrl = options.endpoint ?? `${endpointParam}/client/structure/${clientParam}`;
-  const prefixFromOptions = options?.userAgentOptions?.userAgentPrefix;
-  const userAgentPrefix = prefixFromOptions ? `${prefixFromOptions} azsdk-js-api` : `azsdk-js-api`;
   const { apiVersion: _, ...updatedOptions } = {
     ...options,
-    userAgentOptions: { userAgentPrefix },
     loggingOptions: { logger: options.loggingOptions?.logger ?? logger.info },
   };
   const clientContext = getClient(endpointUrl, undefined, updatedOptions);
@@ -273,11 +267,8 @@ export function createTestService(
 ): TestServiceContext {
   const clientParam = options.clientParam ?? "default";
   const endpointUrl = options.endpoint ?? `${endpointParam}/client/structure/${clientParam}`;
-  const prefixFromOptions = options?.userAgentOptions?.userAgentPrefix;
-  const userAgentPrefix = prefixFromOptions ? `${prefixFromOptions} azsdk-js-api` : `azsdk-js-api`;
   const { apiVersion: _, ...updatedOptions } = {
     ...options,
-    userAgentOptions: { userAgentPrefix },
     loggingOptions: { logger: options.loggingOptions?.logger ?? logger.info },
   };
   const clientContext = getClient(endpointUrl, undefined, updatedOptions);

packages/typespec-ts/test/modular-unit/scenarios/client-context/optionalApiVersion.md

@@ -76,11 +76,8 @@ export function createDataMapService(
   options: DataMapServiceClientOptionalParams = {},
 ): DataMapServiceContext {
   const endpointUrl = options.endpoint ?? String(endpointParam);
-  const prefixFromOptions = options?.userAgentOptions?.userAgentPrefix;
-  const userAgentPrefix = prefixFromOptions ? `${prefixFromOptions} azsdk-js-api` : `azsdk-js-api`;
   const { apiVersion: _, ...updatedOptions } = {
     ...options,
-    userAgentOptions: { userAgentPrefix },
     loggingOptions: { logger: options.loggingOptions?.logger ?? logger.info },
   };
   const clientContext = getClient(endpointUrl, undefined, updatedOptions);

packages/typespec-ts/test/modular-unit/scenarios/operations/header-param/headerParamWithClientInitialization.md

@@ -128,11 +128,8 @@ export function createBillingBenefits(
   options: BillingBenefitsClientOptionalParams = {},
 ): BillingBenefitsContext {
   const endpointUrl = options.endpoint ?? String(endpointParam);
-  const prefixFromOptions = options?.userAgentOptions?.userAgentPrefix;
-  const userAgentPrefix = prefixFromOptions ? `${prefixFromOptions} azsdk-js-api` : `azsdk-js-api`;
   const { apiVersion: _, ...updatedOptions } = {
     ...options,
-    userAgentOptions: { userAgentPrefix },
     loggingOptions: { logger: options.loggingOptions?.logger ?? logger.info },
   };
   const clientContext = getClient(endpointUrl, undefined, updatedOptions);
@@ -360,11 +357,8 @@ export function createBillingBenefits(
   options: BillingBenefitsClientOptionalParams = {},
 ): BillingBenefitsContext {
   const endpointUrl = options.endpoint ?? String(endpointParam);
-  const prefixFromOptions = options?.userAgentOptions?.userAgentPrefix;
-  const userAgentPrefix = prefixFromOptions ? `${prefixFromOptions} azsdk-js-api` : `azsdk-js-api`;
   const { apiVersion: _, ...updatedOptions } = {
     ...options,
-    userAgentOptions: { userAgentPrefix },
     loggingOptions: { logger: options.loggingOptions?.logger ?? logger.info },
   };
   const clientContext = getClient(endpointUrl, undefined, updatedOptions);

packages/typespec-ts/test/modular-unit/scenarios/operations/query-param/queryParamWithClientInitialization.md

@@ -128,11 +128,8 @@ export function createBillingBenefits(
   options: BillingBenefitsClientOptionalParams = {},
 ): BillingBenefitsContext {
   const endpointUrl = options.endpoint ?? String(endpointParam);
-  const prefixFromOptions = options?.userAgentOptions?.userAgentPrefix;
-  const userAgentPrefix = prefixFromOptions ? `${prefixFromOptions} azsdk-js-api` : `azsdk-js-api`;
   const { apiVersion: _, ...updatedOptions } = {
     ...options,
-    userAgentOptions: { userAgentPrefix },
     loggingOptions: { logger: options.loggingOptions?.logger ?? logger.info },
   };
   const clientContext = getClient(endpointUrl, undefined, updatedOptions);
@@ -357,11 +354,8 @@ export function createBillingBenefits(
   options: BillingBenefitsClientOptionalParams = {},
 ): BillingBenefitsContext {
   const endpointUrl = options.endpoint ?? String(endpointParam);
-  const prefixFromOptions = options?.userAgentOptions?.userAgentPrefix;
-  const userAgentPrefix = prefixFromOptions ? `${prefixFromOptions} azsdk-js-api` : `azsdk-js-api`;
   const { apiVersion: _, ...updatedOptions } = {
     ...options,
-    userAgentOptions: { userAgentPrefix },
     loggingOptions: { logger: options.loggingOptions?.logger ?? logger.info },
   };
   const clientContext = getClient(endpointUrl, undefined, updatedOptions);