[dev-tool] Add snippets extraction

common/tools/dev-tool/src/commands/run/update-snippets.ts

@@ -1,4 +1,5 @@
 import fs from "node:fs/promises";
+import { existsSync } from "node:fs";
 import { EOL } from "node:os";
 import path from "node:path";
 import ts from "typescript";
@@ -56,7 +57,9 @@ async function* getAllSnippetFiles(dir: string): AsyncIterable<string> {
 
   yield* findMatchingFiles(path.join(dir, "test"), (name) => name.endsWith(".ts"));
 
-  yield* findMatchingFiles(path.join(dir, "samples-dev"), (name) => name.endsWith(".ts"));
+  if (existsSync(path.join(dir, "samples-dev"))) {
+    yield* findMatchingFiles(path.join(dir, "samples-dev"), (name) => name.endsWith(".ts"));
+  }
 }
 
 /**

sdk/identity/identity-broker/README.md

@@ -8,11 +8,12 @@ An authentication broker is an application that runs on a user’s machine that
 
 ## Getting started
 
-```typescript
-import { nativeBrokerPlugin } from "@azure/identity-broker";
+```ts snippet:getting_started
 import { useIdentityPlugin } from "@azure/identity";
+import { nativeBrokerPlugin } from "@azure/identity-broker";
 
 useIdentityPlugin(nativeBrokerPlugin);
+
 ```
 
 ### Prerequisites
@@ -56,17 +57,18 @@ ms-appx-web://Microsoft.AAD.BrokerPlugin/{client_id}
 
 As of `@azure/identity` version 2.0.0, the Identity client library for JavaScript includes a plugin API. This package (`@azure/identity-broker`) exports a plugin object that you must pass as an argument to the top-level `useIdentityPlugin` function from the `@azure/identity` package. Enable native broker in your program as follows:
 
-```typescript
-import { nativeBrokerPlugin } from "@azure/identity-broker";
+```ts snippet:using_plugins
 import { useIdentityPlugin, InteractiveBrowserCredential } from "@azure/identity";
+import { nativeBrokerPlugin } from "@azure/identity-broker";
 
 useIdentityPlugin(nativeBrokerPlugin);
-
 const credential = new InteractiveBrowserCredential({
   brokerOptions: {
     enabled: true,
+    parentWindowHandle: new Uint8Array(0), // This should be a handle to the parent window
   },
 });
+
 ```
 
 After calling `useIdentityPlugin`, the native broker plugin is registered to the `@azure/identity` package and will be available on the `InteractiveBrowserCredential` that supports WAM broker authentication. This credential has `brokerOptions` in the constructor options.
@@ -75,32 +77,22 @@ After calling `useIdentityPlugin`, the native broker plugin is registered to the
 
 Once the plugin is registered, you can enable WAM broker authentication by passing `brokerOptions` with an `enabled` property set to `true` to a credential constructor. In the following example, we use the `InteractiveBrowserCredential`.
 
-<!-- eslint-skip -->
-```typescript
-import { nativeBrokerPlugin } from "@azure/identity-broker";
+```ts snippet:usage_example
 import { useIdentityPlugin, InteractiveBrowserCredential } from "@azure/identity";
+import { nativeBrokerPlugin } from "@azure/identity-broker";
 
 useIdentityPlugin(nativeBrokerPlugin);
-
-async function main() {
-  const credential = new InteractiveBrowserCredential({
-    brokerOptions: {
-      enabled: true,
-      parentWindowHandle: <insert_current_window_handle>
-    },
-  });
-
-  // We'll use the Microsoft Graph scope as an example
-  const scope = "https://graph.microsoft.com/.default";
-
-  // Print out part of the access token
-  console.log((await credential.getToken(scope)).token.substr(0, 10), "...");
-}
-
-main().catch((error) => {
-  console.error("An error occurred:", error);
-  process.exit(1);
+const credential = new InteractiveBrowserCredential({
+  brokerOptions: {
+    enabled: true,
+    parentWindowHandle: new Uint8Array(0), // This should be a handle to the parent window
+  },
 });
+// We'll use the Microsoft Graph scope as an example
+const scope = "https://graph.microsoft.com/.default";
+// Print out part of the access token
+console.log((await credential.getToken(scope)).token.substring(0, 10), "...");
+
 ```
 
 For a complete example of using an Electron app for retrieving a window handle, see [this sample](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity-broker/samples/v1/typescript/src/index.ts).
@@ -109,33 +101,23 @@ For a complete example of using an Electron app for retrieving a window handle,
 
 When the `useDefaultBrokerAccount` option is set to `true`, the credential will attempt to silently use the default broker account. If using the default account fails, the credential will fall back to interactive authentication.
 
-<!-- eslint-skip -->
-```typescript
-import { nativeBrokerPlugin } from "@azure/identity-broker";
+```ts snippet:use_default_account
 import { useIdentityPlugin, InteractiveBrowserCredential } from "@azure/identity";
+import { nativeBrokerPlugin } from "@azure/identity-broker";
 
 useIdentityPlugin(nativeBrokerPlugin);
-
-async function main() {
-  const credential = new InteractiveBrowserCredential({
-    brokerOptions: {
-      enabled: true,
-      useDefaultBrokerAccount: true,
-      parentWindowHandle: <insert_current_window_handle>
-    },
-  });
-
-  // We'll use the Microsoft Graph scope as an example
-  const scope = "https://graph.microsoft.com/.default";
-
-  // Print out part of the access token
-  console.log((await credential.getToken(scope)).token.substr(0, 10), "...");
-}
-
-main().catch((error) => {
-  console.error("An error occurred:", error);
-  process.exit(1);
+const credential = new InteractiveBrowserCredential({
+  brokerOptions: {
+    enabled: true,
+    useDefaultBrokerAccount: true,
+    parentWindowHandle: new Uint8Array(0), // This should be a handle to the parent window
+  },
 });
+// We'll use the Microsoft Graph scope as an example
+const scope = "https://graph.microsoft.com/.default";
+// Print out part of the access token
+console.log((await credential.getToken(scope)).token.substr(0, 10), "...");
+
 ```
 
 ## Troubleshooting
@@ -146,10 +128,11 @@ See the Azure Identity [troubleshooting guide][https://github.com/Azure/azure-sd
 
 Enabling logging may help uncover useful information about failures. In order to see a log of HTTP requests and responses, set the `AZURE_LOG_LEVEL` environment variable to `info`. Alternatively, logging can be enabled at runtime by calling `setLogLevel` in the `@azure/logger`:
 
-```typescript
+```ts snippet:logging
 import { setLogLevel } from "@azure/logger";
 
 setLogLevel("info");
+
 ```
 
 ## Next steps

sdk/identity/identity-broker/eslint.config.mjs

@@ -7,4 +7,11 @@ export default [
       "@azure/azure-sdk/ts-package-json-module": "warn",
     },
   },
+  {
+    files: ["test/snippets.spec.ts"],
+    rules: {
+      "@typescript-eslint/ban-ts-comment": "off",
+      "@typescript-eslint/no-unused-vars": "off",
+    },
+  },
 ];

sdk/identity/identity-broker/package.json

@@ -4,7 +4,7 @@
   "sdk-type": "client",
   "description": "A native plugin for Azure Identity credentials to enable broker authentication such as WAM",
   "main": "dist/index.js",
-  "module": "dist-esm/identity-broker/src/index.js",
+  "module": "dist-esm/src/index.js",
   "types": "./types/identity-broker.d.ts",
   "scripts": {
     "audit": "node ../../../common/scripts/rush-audit.js && rimraf node_modules package-lock.json && npm i --package-lock-only 2>&1 && npm audit",
@@ -15,6 +15,7 @@
     "clean": "rimraf --glob dist dist-esm types \"*.tgz\" \"*.log\"",
     "execute:samples": "echo skipped",
     "extract-api": "tsc -p . && dev-tool run extract-api",
+    "extract-snippets": "dev-tool run update-snippets",
     "format": "dev-tool run vendored prettier --write --config ../../../.prettierrc.json --ignore-path ../../../.prettierignore \"src/**/*.ts\" \"test/**/*.ts\" \"*.{js,json}\"",
     "integration-test:browser": "echo skipped",
     "integration-test:node": "echo skipped",

sdk/identity/identity-broker/src/index.ts

@@ -13,12 +13,18 @@ import { NativeBrokerPlugin } from "@azure/msal-node-extensions";
  *
  * Example:
  *
- * ```typescript
- * import { useIdentityPlugin, DeviceCodeCredential } from "@azure/identity";
+ * ```ts snippet:using_plugins
+ * import { useIdentityPlugin, InteractiveBrowserCredential } from "@azure/identity";
  * import { nativeBrokerPlugin } from "@azure/identity-broker";
  *
- * // Load the plugin
  * useIdentityPlugin(nativeBrokerPlugin);
+ * const credential = new InteractiveBrowserCredential({
+ *   brokerOptions: {
+ *     enabled: true,
+ *     parentWindowHandle: new Uint8Array(0), // This should be a handle to the parent window
+ *   },
+ * });
+ *
  * ```
  */
 

sdk/identity/identity-broker/test/snippets.spec.ts

@@ -0,0 +1,63 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { InteractiveBrowserCredential, useIdentityPlugin } from "@azure/identity";
+import { nativeBrokerPlugin } from "@azure/identity-broker";
+import { setLogLevel } from "@azure/logger";
+
+describe("snippets", function () {
+  it("getting_started", function () {
+    useIdentityPlugin(nativeBrokerPlugin);
+  });
+
+  it("using_plugins", async function () {
+    useIdentityPlugin(nativeBrokerPlugin);
+
+    // @ts-ignore
+    const credential = new InteractiveBrowserCredential({
+      brokerOptions: {
+        enabled: true,
+        parentWindowHandle: new Uint8Array(0), // This should be a handle to the parent window
+      },
+    });
+  });
+
+  it("usage_example", async function () {
+    useIdentityPlugin(nativeBrokerPlugin);
+
+    const credential = new InteractiveBrowserCredential({
+      brokerOptions: {
+        enabled: true,
+        parentWindowHandle: new Uint8Array(0), // This should be a handle to the parent window
+      },
+    });
+
+    // We'll use the Microsoft Graph scope as an example
+    const scope = "https://graph.microsoft.com/.default";
+
+    // Print out part of the access token
+    console.log((await credential.getToken(scope)).token.substring(0, 10), "...");
+  });
+
+  it("use_default_account", async function () {
+    useIdentityPlugin(nativeBrokerPlugin);
+
+    const credential = new InteractiveBrowserCredential({
+      brokerOptions: {
+        enabled: true,
+        useDefaultBrokerAccount: true,
+        parentWindowHandle: new Uint8Array(0), // This should be a handle to the parent window
+      },
+    });
+
+    // We'll use the Microsoft Graph scope as an example
+    const scope = "https://graph.microsoft.com/.default";
+
+    // Print out part of the access token
+    console.log((await credential.getToken(scope)).token.substr(0, 10), "...");
+  });
+
+  it("logging", async function () {
+    setLogLevel("info");
+  });
+});

sdk/identity/identity/BREAKING_CHANGES.md

@@ -14,18 +14,24 @@ As of `@azure/identity` 3.0.0, the default behavior of credentials supporting mu
 
 - Add all IDs, of tenants from which tokens should be acquired, to the `additionallyAllowedTenants` array in the credential options. For example:
 
-```typescript Snippet:Identity_BreakingChanges_AddExplicitAdditionallyAllowedTenants
+```typescript snippet:identity_breakingchanges_addexplicitadditionallyallowedtenants
+import { DefaultAzureCredential } from "@azure/identity";
+
 const credential = new DefaultAzureCredential({
   additionallyAllowedTenants: ["<tenant_id_1>", "<tenant_id_2>"],
 });
+
 ```
 
 - Add `*` to enable token acquisition from any tenant, which is the original behavior. For example:
 
-```typescript Snippet:Identity_BreakingChanges_AddAllAdditionallyAllowedTenants
+```typescript snippet:identity_breakingchanges_addalladditionallyallowedtenants
+import { DefaultAzureCredential } from "@azure/identity";
+
 const credential = new DefaultAzureCredential({
   additionallyAllowedTenants: ["*"],
 });
+
 ```
 
 Note: Credential types which do not require a `tenantId` on construction will only throw an error when the application has provided a value for `tenantId` either in the options or via a constructor overload. If no `tenantId` is specified when constructing the credential, the credential will acquire tokens for any requested `tenantId` regardless of the value of `additionallyAllowedTenants`.

sdk/identity/identity/CHANGELOG.md

@@ -1,5 +1,7 @@
 # Release History
 
+<!-- dev-tool snippets ignore -->
+
 ## 4.5.0-beta.3 (Unreleased)
 
 ### Features Added