@microsoft/teams.client 0.2.7

package/README.md

@@ -0,0 +1,37 @@
+# Teams: Client
+
+<p>
+    <a href="https://www.npmjs.com/package/@microsoft/teams.client" target="_blank">
+        <img src="https://img.shields.io/npm/v/@microsoft/teams.client" />
+    </a>
+    <a href="https://www.npmjs.com/package/@microsoft/teams.client?activeTab=code" target="_blank">
+        <img src="https://img.shields.io/bundlephobia/min/@microsoft/teams.client" />
+    </a>
+    <a href="https://www.npmjs.com/package/@microsoft/teams.client?activeTab=dependencies" target="_blank">
+        <img src="https://img.shields.io/librariesio/release/npm/@microsoft/teams.client" />
+    </a>
+    <a href="https://www.npmjs.com/package/@microsoft/teams.client" target="_blank">
+        <img src="https://img.shields.io/npm/dw/@microsoft/teams.client" />
+    </a>
+    <a href="https://microsoft.github.io/teams.js" target="_blank">
+        <img src="https://img.shields.io/badge/📖 docs-open-blue" />
+    </a>
+</p>
+
+A client used to create app/bot surfaces such as tabs.
+
+<a href="https://microsoft.github.io/teams.js/2.getting-started/1.create-application.html" target="_blank">
+    <img src="https://img.shields.io/badge/📖 Getting Started-blue?style=for-the-badge" />
+</a>
+
+## Install
+
+```bash
+$: npm install @microsoft/teams.client
+```
+
+## Dependencies
+
+## Links
+
+- https://learn.microsoft.com/en-us/microsoftteams/platform/tabs/what-are-tabs?tabs=personal

package/dist/app.d.mts

@@ -0,0 +1,92 @@
+import * as msal from '@azure/msal-browser';
+import * as http from '@microsoft/teams.common/http';
+import { ILogger } from '@microsoft/teams.common/logging';
+import * as teamsJs from '@microsoft/teams-js';
+
+type MsalOptions = {
+    /**
+     * Optional MSAL configuration. This parameter is used to construct an MSAL instance in order
+     * to make authenticated function calls. If omitted, a default configuration is created.
+     */
+    readonly configuration?: msal.Configuration;
+    /**
+     * Default token request options used when acquiring a token.
+     */
+    readonly defaultSilentRequest?: msal.SilentRequest;
+};
+type AppOptions = {
+    /**
+     * The app base url.
+     */
+    readonly baseUrl?: string;
+    /** App tenant ID */
+    readonly tenantId?: string;
+    /**
+     * Logger instance to use.
+     */
+    readonly logger?: ILogger;
+    /**
+     * Options to control how MSAL is initialized and used.
+     */
+    readonly msalOptions?: MsalOptions;
+};
+type AppState = {
+    phase: 'stopped' | 'starting';
+    startedAt?: never;
+    msalInstance?: never;
+    context?: never;
+} | {
+    phase: 'started';
+    startedAt: Date;
+    msalInstance: msal.IPublicClientApplication;
+    context: teamsJs.app.Context;
+};
+type ExecOptions = ({
+    msalTokenRequest: msal.SilentRequest;
+    permission?: never;
+} | {
+    msalTokenRequest?: never;
+    permission: string;
+} | {
+    msalTokenRequest?: never;
+    permission?: never;
+}) & {
+    requestHeaders?: Record<string, string>;
+};
+declare class App {
+    readonly options: AppOptions;
+    readonly http: http.Client;
+    readonly clientId: string;
+    protected _state: AppState;
+    /**
+     * the apps logger
+     */
+    get log(): ILogger;
+    protected _log: ILogger;
+    /**
+     * the date/time when the app was successfully started.
+     */
+    get startedAt(): Date | undefined;
+    /** the msal instance used in this app. undefined until the app is started. */
+    get msalInstance(): msal.IPublicClientApplication | undefined;
+    constructor(clientId: string, options?: AppOptions);
+    /**
+     * Starts the library and initializes the dependent teams-js and MSAL libraries.
+     * @returns A promise that will be fulfilled when the app has started, or
+     *          rejected if the initialization fails or times out.
+     */
+    start(): Promise<void>;
+    /**
+     * Execute a server-side function
+     * @param name The unique function name
+     * @param data The data to send
+     * @param options Options
+     * @param options.msalTokenRequest Optional MSAL token request.
+     * If omitted, a default token request is used.
+     * @param options.requestHeaders Optional additional request headers.
+     * @returns The function response
+     */
+    exec<T = unknown>(name: string, data?: unknown, options?: ExecOptions): Promise<T>;
+}
+
+export { App, type AppOptions, type MsalOptions };

package/dist/app.d.ts

@@ -0,0 +1,92 @@
+import * as msal from '@azure/msal-browser';
+import * as http from '@microsoft/teams.common/http';
+import { ILogger } from '@microsoft/teams.common/logging';
+import * as teamsJs from '@microsoft/teams-js';
+
+type MsalOptions = {
+    /**
+     * Optional MSAL configuration. This parameter is used to construct an MSAL instance in order
+     * to make authenticated function calls. If omitted, a default configuration is created.
+     */
+    readonly configuration?: msal.Configuration;
+    /**
+     * Default token request options used when acquiring a token.
+     */
+    readonly defaultSilentRequest?: msal.SilentRequest;
+};
+type AppOptions = {
+    /**
+     * The app base url.
+     */
+    readonly baseUrl?: string;
+    /** App tenant ID */
+    readonly tenantId?: string;
+    /**
+     * Logger instance to use.
+     */
+    readonly logger?: ILogger;
+    /**
+     * Options to control how MSAL is initialized and used.
+     */
+    readonly msalOptions?: MsalOptions;
+};
+type AppState = {
+    phase: 'stopped' | 'starting';
+    startedAt?: never;
+    msalInstance?: never;
+    context?: never;
+} | {
+    phase: 'started';
+    startedAt: Date;
+    msalInstance: msal.IPublicClientApplication;
+    context: teamsJs.app.Context;
+};
+type ExecOptions = ({
+    msalTokenRequest: msal.SilentRequest;
+    permission?: never;
+} | {
+    msalTokenRequest?: never;
+    permission: string;
+} | {
+    msalTokenRequest?: never;
+    permission?: never;
+}) & {
+    requestHeaders?: Record<string, string>;
+};
+declare class App {
+    readonly options: AppOptions;
+    readonly http: http.Client;
+    readonly clientId: string;
+    protected _state: AppState;
+    /**
+     * the apps logger
+     */
+    get log(): ILogger;
+    protected _log: ILogger;
+    /**
+     * the date/time when the app was successfully started.
+     */
+    get startedAt(): Date | undefined;
+    /** the msal instance used in this app. undefined until the app is started. */
+    get msalInstance(): msal.IPublicClientApplication | undefined;
+    constructor(clientId: string, options?: AppOptions);
+    /**
+     * Starts the library and initializes the dependent teams-js and MSAL libraries.
+     * @returns A promise that will be fulfilled when the app has started, or
+     *          rejected if the initialization fails or times out.
+     */
+    start(): Promise<void>;
+    /**
+     * Execute a server-side function
+     * @param name The unique function name
+     * @param data The data to send
+     * @param options Options
+     * @param options.msalTokenRequest Optional MSAL token request.
+     * If omitted, a default token request is used.
+     * @param options.requestHeaders Optional additional request headers.
+     * @returns The function response
+     */
+    exec<T = unknown>(name: string, data?: unknown, options?: ExecOptions): Promise<T>;
+}
+
+export { App, type AppOptions, type MsalOptions };

package/dist/app.js

@@ -0,0 +1,122 @@
+'use strict';
+
+var msal = require('@azure/msal-browser');
+var http = require('@microsoft/teams.common/http');
+var logging = require('@microsoft/teams.common/logging');
+var teamsJs = require('@microsoft/teams-js');
+var msalUtils = require('./msal-utils');
+
+function _interopNamespace(e) {
+  if (e && e.__esModule) return e;
+  var n = Object.create(null);
+  if (e) {
+    Object.keys(e).forEach(function (k) {
+      if (k !== 'default') {
+        var d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: function () { return e[k]; }
+        });
+      }
+    });
+  }
+  n.default = e;
+  return Object.freeze(n);
+}
+
+var msal__namespace = /*#__PURE__*/_interopNamespace(msal);
+var http__namespace = /*#__PURE__*/_interopNamespace(http);
+var teamsJs__namespace = /*#__PURE__*/_interopNamespace(teamsJs);
+
+class App {
+  options;
+  http;
+  clientId;
+  _state = { phase: "stopped" };
+  /**
+   * the apps logger
+   */
+  get log() {
+    return this._log;
+  }
+  _log;
+  /**
+   * the date/time when the app was successfully started.
+   */
+  get startedAt() {
+    return this._state?.startedAt;
+  }
+  /** the msal instance used in this app. undefined until the app is started. */
+  get msalInstance() {
+    return this._state.msalInstance;
+  }
+  constructor(clientId, options = {}) {
+    if (!clientId) {
+      throw new Error("Invalid client ID.");
+    }
+    this.clientId = clientId;
+    this.options = options;
+    this._log = options?.logger || new logging.ConsoleLogger("@teams/client");
+    this.http = new http__namespace.Client({ baseUrl: options?.baseUrl });
+  }
+  /**
+   * Starts the library and initializes the dependent teams-js and MSAL libraries.
+   * @returns A promise that will be fulfilled when the app has started, or
+   *          rejected if the initialization fails or times out.
+   */
+  async start() {
+    if (this._state.phase !== "stopped") {
+      this._log.debug(`app already ${this._state.phase}`);
+      return;
+    }
+    this._log.debug("app starting");
+    this._state = { phase: "starting" };
+    await teamsJs__namespace.app.initialize();
+    const context = await teamsJs__namespace.app.getContext();
+    const msalConfig = this.options.msalOptions?.configuration ?? msalUtils.buildMsalConfig(this.clientId, this._log);
+    const msalInstance = await msal__namespace.createNestablePublicClientApplication(msalConfig);
+    await msalInstance.initialize();
+    this._state = { phase: "started", msalInstance, context, startedAt: /* @__PURE__ */ new Date() };
+    this._log.debug("app started");
+  }
+  /**
+   * Execute a server-side function
+   * @param name The unique function name
+   * @param data The data to send
+   * @param options Options
+   * @param options.msalTokenRequest Optional MSAL token request.
+   * If omitted, a default token request is used.
+   * @param options.requestHeaders Optional additional request headers.
+   * @returns The function response
+   */
+  async exec(name, data, options) {
+    if (this._state.phase !== "started") {
+      throw new Error("App not started");
+    }
+    const { context } = this._state;
+    const accessToken = await msalUtils.acquireMsalAccessToken(
+      this._state.msalInstance,
+      options?.msalTokenRequest ?? msalUtils.getStandardExecSilentRequest(this.clientId, options?.permission),
+      this._log
+    );
+    const res = await this.http.post(`/api/functions/${name}`, data, {
+      headers: {
+        authorization: `Bearer ${accessToken}`,
+        "x-teams-app-session-id": context.app.sessionId,
+        "x-teams-channel-id": context.channel?.id,
+        "x-teams-chat-id": context.chat?.id,
+        "x-teams-meeting-id": context.meeting?.id,
+        "x-teams-message-id": context.app.parentMessageId,
+        "x-teams-page-id": context.page.id,
+        "x-teams-sub-page-id": context.page.subPageId,
+        "x-teams-team-id": context.team?.internalId,
+        ...options?.requestHeaders ?? {}
+      }
+    });
+    return res.data;
+  }
+}
+
+exports.App = App;
+//# sourceMappingURL=app.js.map
+//# sourceMappingURL=app.js.map

package/dist/app.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/app.ts"],"names":["ConsoleLogger","http","teamsJs","buildMsalConfig","msal","acquireMsalAccessToken","getStandardExecSilentRequest"],"mappings":"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","file":"app.js","sourcesContent":["import * as msal from '@azure/msal-browser';\nimport * as http from '@microsoft/teams.common/http';\nimport { ILogger, ConsoleLogger } from '@microsoft/teams.common/logging';\nimport * as teamsJs from '@microsoft/teams-js';\n\nimport {\n  acquireMsalAccessToken,\n  buildMsalConfig,\n  getStandardExecSilentRequest,\n} from './msal-utils';\n\nexport type MsalOptions = {\n  /**\n   * Optional MSAL configuration. This parameter is used to construct an MSAL instance in order\n   * to make authenticated function calls. If omitted, a default configuration is created.\n   */\n  readonly configuration?: msal.Configuration;\n  /**\n   * Default token request options used when acquiring a token.\n   */\n  readonly defaultSilentRequest?: msal.SilentRequest;\n};\n\nexport type AppOptions = {\n  /**\n   * The app base url.\n   */\n  readonly baseUrl?: string;\n\n  /** App tenant ID */\n  readonly tenantId?: string;\n\n  /**\n   * Logger instance to use.\n   */\n  readonly logger?: ILogger;\n\n  /**\n   * Options to control how MSAL is initialized and used.\n   */\n  readonly msalOptions?: MsalOptions;\n};\n\ntype AppState =\n  | {\n      phase: 'stopped' | 'starting';\n      startedAt?: never;\n      msalInstance?: never;\n      context?: never;\n    }\n  | {\n      phase: 'started';\n      startedAt: Date;\n      msalInstance: msal.IPublicClientApplication;\n      context: teamsJs.app.Context;\n    };\n\ntype ExecOptions = (\n  | { msalTokenRequest: msal.SilentRequest; permission?: never }\n  | { msalTokenRequest?: never; permission: string }\n  | { msalTokenRequest?: never; permission?: never }\n) & {\n  requestHeaders?: Record<string, string>;\n};\n\nexport class App {\n  readonly options: AppOptions;\n  readonly http: http.Client;\n  readonly clientId: string;\n  protected _state: AppState = { phase: 'stopped' };\n\n  /**\n   * the apps logger\n   */\n  get log() {\n    return this._log;\n  }\n  protected _log: ILogger;\n\n  /**\n   * the date/time when the app was successfully started.\n   */\n  get startedAt() {\n    return this._state?.startedAt;\n  }\n\n  /** the msal instance used in this app. undefined until the app is started. */\n  get msalInstance() {\n    return this._state.msalInstance;\n  }\n\n  constructor(clientId: string, options: AppOptions = {}) {\n    if (!clientId) {\n      throw new Error('Invalid client ID.');\n    }\n\n    this.clientId = clientId;\n    this.options = options;\n    this._log = options?.logger || new ConsoleLogger('@teams/client');\n    this.http = new http.Client({ baseUrl: options?.baseUrl });\n  }\n\n  /**\n   * Starts the library and initializes the dependent teams-js and MSAL libraries.\n   * @returns A promise that will be fulfilled when the app has started, or\n   *          rejected if the initialization fails or times out.\n   */\n  async start(): Promise<void> {\n    if (this._state.phase !== 'stopped') {\n      this._log.debug(`app already ${this._state.phase}`);\n      return;\n    }\n\n    this._log.debug('app starting');\n    this._state = { phase: 'starting' };\n\n    await teamsJs.app.initialize();\n    const context = await teamsJs.app.getContext();\n\n    const msalConfig =\n      this.options.msalOptions?.configuration ?? buildMsalConfig(this.clientId, this._log);\n    const msalInstance = await msal.createNestablePublicClientApplication(msalConfig);\n    await msalInstance.initialize();\n\n    this._state = { phase: 'started', msalInstance, context, startedAt: new Date() };\n    this._log.debug('app started');\n  }\n\n  /**\n   * Execute a server-side function\n   * @param name The unique function name\n   * @param data The data to send\n   * @param options Options\n   * @param options.msalTokenRequest Optional MSAL token request.\n   * If omitted, a default token request is used.\n   * @param options.requestHeaders Optional additional request headers.\n   * @returns The function response\n   */\n  async exec<T = unknown>(name: string, data?: unknown, options?: ExecOptions): Promise<T> {\n    if (this._state.phase !== 'started') {\n      throw new Error('App not started');\n    }\n\n    const { context } = this._state;\n    const accessToken = await acquireMsalAccessToken(\n      this._state.msalInstance,\n      options?.msalTokenRequest ?? getStandardExecSilentRequest(this.clientId, options?.permission),\n      this._log\n    );\n\n    const res = await this.http.post<T>(`/api/functions/${name}`, data, {\n      headers: {\n        authorization: `Bearer ${accessToken}`,\n        'x-teams-app-session-id': context.app.sessionId,\n        'x-teams-channel-id': context.channel?.id,\n        'x-teams-chat-id': context.chat?.id,\n        'x-teams-meeting-id': context.meeting?.id,\n        'x-teams-message-id': context.app.parentMessageId,\n        'x-teams-page-id': context.page.id,\n        'x-teams-sub-page-id': context.page.subPageId,\n        'x-teams-team-id': context.team?.internalId,\n        ...(options?.requestHeaders ?? {}),\n      },\n    });\n\n    return res.data;\n  }\n}\n"]}

package/dist/app.mjs

@@ -0,0 +1,98 @@
+import * as msal from '@azure/msal-browser';
+import * as http from '@microsoft/teams.common/http';
+import { ConsoleLogger } from '@microsoft/teams.common/logging';
+import * as teamsJs from '@microsoft/teams-js';
+import { buildMsalConfig, acquireMsalAccessToken, getStandardExecSilentRequest } from './msal-utils';
+
+class App {
+  options;
+  http;
+  clientId;
+  _state = { phase: "stopped" };
+  /**
+   * the apps logger
+   */
+  get log() {
+    return this._log;
+  }
+  _log;
+  /**
+   * the date/time when the app was successfully started.
+   */
+  get startedAt() {
+    return this._state?.startedAt;
+  }
+  /** the msal instance used in this app. undefined until the app is started. */
+  get msalInstance() {
+    return this._state.msalInstance;
+  }
+  constructor(clientId, options = {}) {
+    if (!clientId) {
+      throw new Error("Invalid client ID.");
+    }
+    this.clientId = clientId;
+    this.options = options;
+    this._log = options?.logger || new ConsoleLogger("@teams/client");
+    this.http = new http.Client({ baseUrl: options?.baseUrl });
+  }
+  /**
+   * Starts the library and initializes the dependent teams-js and MSAL libraries.
+   * @returns A promise that will be fulfilled when the app has started, or
+   *          rejected if the initialization fails or times out.
+   */
+  async start() {
+    if (this._state.phase !== "stopped") {
+      this._log.debug(`app already ${this._state.phase}`);
+      return;
+    }
+    this._log.debug("app starting");
+    this._state = { phase: "starting" };
+    await teamsJs.app.initialize();
+    const context = await teamsJs.app.getContext();
+    const msalConfig = this.options.msalOptions?.configuration ?? buildMsalConfig(this.clientId, this._log);
+    const msalInstance = await msal.createNestablePublicClientApplication(msalConfig);
+    await msalInstance.initialize();
+    this._state = { phase: "started", msalInstance, context, startedAt: /* @__PURE__ */ new Date() };
+    this._log.debug("app started");
+  }
+  /**
+   * Execute a server-side function
+   * @param name The unique function name
+   * @param data The data to send
+   * @param options Options
+   * @param options.msalTokenRequest Optional MSAL token request.
+   * If omitted, a default token request is used.
+   * @param options.requestHeaders Optional additional request headers.
+   * @returns The function response
+   */
+  async exec(name, data, options) {
+    if (this._state.phase !== "started") {
+      throw new Error("App not started");
+    }
+    const { context } = this._state;
+    const accessToken = await acquireMsalAccessToken(
+      this._state.msalInstance,
+      options?.msalTokenRequest ?? getStandardExecSilentRequest(this.clientId, options?.permission),
+      this._log
+    );
+    const res = await this.http.post(`/api/functions/${name}`, data, {
+      headers: {
+        authorization: `Bearer ${accessToken}`,
+        "x-teams-app-session-id": context.app.sessionId,
+        "x-teams-channel-id": context.channel?.id,
+        "x-teams-chat-id": context.chat?.id,
+        "x-teams-meeting-id": context.meeting?.id,
+        "x-teams-message-id": context.app.parentMessageId,
+        "x-teams-page-id": context.page.id,
+        "x-teams-sub-page-id": context.page.subPageId,
+        "x-teams-team-id": context.team?.internalId,
+        ...options?.requestHeaders ?? {}
+      }
+    });
+    return res.data;
+  }
+}
+
+export { App };
+//# sourceMappingURL=app.mjs.map
+//# sourceMappingURL=app.mjs.map

package/dist/app.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/app.ts"],"names":[],"mappings":";;;;;;AAiEO,MAAM,GAAI,CAAA;AAAA,EACN,OAAA;AAAA,EACA,IAAA;AAAA,EACA,QAAA;AAAA,EACC,MAAA,GAAmB,EAAE,KAAA,EAAO,SAAU,EAAA;AAAA;AAAA;AAAA;AAAA,EAKhD,IAAI,GAAM,GAAA;AACR,IAAA,OAAO,IAAK,CAAA,IAAA;AAAA;AACd,EACU,IAAA;AAAA;AAAA;AAAA;AAAA,EAKV,IAAI,SAAY,GAAA;AACd,IAAA,OAAO,KAAK,MAAQ,EAAA,SAAA;AAAA;AACtB;AAAA,EAGA,IAAI,YAAe,GAAA;AACjB,IAAA,OAAO,KAAK,MAAO,CAAA,YAAA;AAAA;AACrB,EAEA,WAAY,CAAA,QAAA,EAAkB,OAAsB,GAAA,EAAI,EAAA;AACtD,IAAA,IAAI,CAAC,QAAU,EAAA;AACb,MAAM,MAAA,IAAI,MAAM,oBAAoB,CAAA;AAAA;AAGtC,IAAA,IAAA,CAAK,QAAW,GAAA,QAAA;AAChB,IAAA,IAAA,CAAK,OAAU,GAAA,OAAA;AACf,IAAA,IAAA,CAAK,IAAO,GAAA,OAAA,EAAS,MAAU,IAAA,IAAI,cAAc,eAAe,CAAA;AAChE,IAAK,IAAA,CAAA,IAAA,GAAO,IAAI,IAAK,CAAA,MAAA,CAAO,EAAE,OAAS,EAAA,OAAA,EAAS,SAAS,CAAA;AAAA;AAC3D;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAM,KAAuB,GAAA;AAC3B,IAAI,IAAA,IAAA,CAAK,MAAO,CAAA,KAAA,KAAU,SAAW,EAAA;AACnC,MAAA,IAAA,CAAK,KAAK,KAAM,CAAA,CAAA,YAAA,EAAe,IAAK,CAAA,MAAA,CAAO,KAAK,CAAE,CAAA,CAAA;AAClD,MAAA;AAAA;AAGF,IAAK,IAAA,CAAA,IAAA,CAAK,MAAM,cAAc,CAAA;AAC9B,IAAK,IAAA,CAAA,MAAA,GAAS,EAAE,KAAA,EAAO,UAAW,EAAA;AAElC,IAAM,MAAA,OAAA,CAAQ,IAAI,UAAW,EAAA;AAC7B,IAAA,MAAM,OAAU,GAAA,MAAM,OAAQ,CAAA,GAAA,CAAI,UAAW,EAAA;AAE7C,IAAM,MAAA,UAAA,GACJ,KAAK,OAAQ,CAAA,WAAA,EAAa,iBAAiB,eAAgB,CAAA,IAAA,CAAK,QAAU,EAAA,IAAA,CAAK,IAAI,CAAA;AACrF,IAAA,MAAM,YAAe,GAAA,MAAM,IAAK,CAAA,qCAAA,CAAsC,UAAU,CAAA;AAChF,IAAA,MAAM,aAAa,UAAW,EAAA;AAE9B,IAAK,IAAA,CAAA,MAAA,GAAS,EAAE,KAAO,EAAA,SAAA,EAAW,cAAc,OAAS,EAAA,SAAA,kBAAe,IAAA,IAAA,EAAO,EAAA;AAC/E,IAAK,IAAA,CAAA,IAAA,CAAK,MAAM,aAAa,CAAA;AAAA;AAC/B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYA,MAAM,IAAA,CAAkB,IAAc,EAAA,IAAA,EAAgB,OAAmC,EAAA;AACvF,IAAI,IAAA,IAAA,CAAK,MAAO,CAAA,KAAA,KAAU,SAAW,EAAA;AACnC,MAAM,MAAA,IAAI,MAAM,iBAAiB,CAAA;AAAA;AAGnC,IAAM,MAAA,EAAE,OAAQ,EAAA,GAAI,IAAK,CAAA,MAAA;AACzB,IAAA,MAAM,cAAc,MAAM,sBAAA;AAAA,MACxB,KAAK,MAAO,CAAA,YAAA;AAAA,MACZ,SAAS,gBAAoB,IAAA,4BAAA,CAA6B,IAAK,CAAA,QAAA,EAAU,SAAS,UAAU,CAAA;AAAA,MAC5F,IAAK,CAAA;AAAA,KACP;AAEA,IAAM,MAAA,GAAA,GAAM,MAAM,IAAK,CAAA,IAAA,CAAK,KAAQ,CAAkB,eAAA,EAAA,IAAI,IAAI,IAAM,EAAA;AAAA,MAClE,OAAS,EAAA;AAAA,QACP,aAAA,EAAe,UAAU,WAAW,CAAA,CAAA;AAAA,QACpC,wBAAA,EAA0B,QAAQ,GAAI,CAAA,SAAA;AAAA,QACtC,oBAAA,EAAsB,QAAQ,OAAS,EAAA,EAAA;AAAA,QACvC,iBAAA,EAAmB,QAAQ,IAAM,EAAA,EAAA;AAAA,QACjC,oBAAA,EAAsB,QAAQ,OAAS,EAAA,EAAA;AAAA,QACvC,oBAAA,EAAsB,QAAQ,GAAI,CAAA,eAAA;AAAA,QAClC,iBAAA,EAAmB,QAAQ,IAAK,CAAA,EAAA;AAAA,QAChC,qBAAA,EAAuB,QAAQ,IAAK,CAAA,SAAA;AAAA,QACpC,iBAAA,EAAmB,QAAQ,IAAM,EAAA,UAAA;AAAA,QACjC,GAAI,OAAS,EAAA,cAAA,IAAkB;AAAC;AAClC,KACD,CAAA;AAED,IAAA,OAAO,GAAI,CAAA,IAAA;AAAA;AAEf","file":"app.mjs","sourcesContent":["import * as msal from '@azure/msal-browser';\nimport * as http from '@microsoft/teams.common/http';\nimport { ILogger, ConsoleLogger } from '@microsoft/teams.common/logging';\nimport * as teamsJs from '@microsoft/teams-js';\n\nimport {\n  acquireMsalAccessToken,\n  buildMsalConfig,\n  getStandardExecSilentRequest,\n} from './msal-utils';\n\nexport type MsalOptions = {\n  /**\n   * Optional MSAL configuration. This parameter is used to construct an MSAL instance in order\n   * to make authenticated function calls. If omitted, a default configuration is created.\n   */\n  readonly configuration?: msal.Configuration;\n  /**\n   * Default token request options used when acquiring a token.\n   */\n  readonly defaultSilentRequest?: msal.SilentRequest;\n};\n\nexport type AppOptions = {\n  /**\n   * The app base url.\n   */\n  readonly baseUrl?: string;\n\n  /** App tenant ID */\n  readonly tenantId?: string;\n\n  /**\n   * Logger instance to use.\n   */\n  readonly logger?: ILogger;\n\n  /**\n   * Options to control how MSAL is initialized and used.\n   */\n  readonly msalOptions?: MsalOptions;\n};\n\ntype AppState =\n  | {\n      phase: 'stopped' | 'starting';\n      startedAt?: never;\n      msalInstance?: never;\n      context?: never;\n    }\n  | {\n      phase: 'started';\n      startedAt: Date;\n      msalInstance: msal.IPublicClientApplication;\n      context: teamsJs.app.Context;\n    };\n\ntype ExecOptions = (\n  | { msalTokenRequest: msal.SilentRequest; permission?: never }\n  | { msalTokenRequest?: never; permission: string }\n  | { msalTokenRequest?: never; permission?: never }\n) & {\n  requestHeaders?: Record<string, string>;\n};\n\nexport class App {\n  readonly options: AppOptions;\n  readonly http: http.Client;\n  readonly clientId: string;\n  protected _state: AppState = { phase: 'stopped' };\n\n  /**\n   * the apps logger\n   */\n  get log() {\n    return this._log;\n  }\n  protected _log: ILogger;\n\n  /**\n   * the date/time when the app was successfully started.\n   */\n  get startedAt() {\n    return this._state?.startedAt;\n  }\n\n  /** the msal instance used in this app. undefined until the app is started. */\n  get msalInstance() {\n    return this._state.msalInstance;\n  }\n\n  constructor(clientId: string, options: AppOptions = {}) {\n    if (!clientId) {\n      throw new Error('Invalid client ID.');\n    }\n\n    this.clientId = clientId;\n    this.options = options;\n    this._log = options?.logger || new ConsoleLogger('@teams/client');\n    this.http = new http.Client({ baseUrl: options?.baseUrl });\n  }\n\n  /**\n   * Starts the library and initializes the dependent teams-js and MSAL libraries.\n   * @returns A promise that will be fulfilled when the app has started, or\n   *          rejected if the initialization fails or times out.\n   */\n  async start(): Promise<void> {\n    if (this._state.phase !== 'stopped') {\n      this._log.debug(`app already ${this._state.phase}`);\n      return;\n    }\n\n    this._log.debug('app starting');\n    this._state = { phase: 'starting' };\n\n    await teamsJs.app.initialize();\n    const context = await teamsJs.app.getContext();\n\n    const msalConfig =\n      this.options.msalOptions?.configuration ?? buildMsalConfig(this.clientId, this._log);\n    const msalInstance = await msal.createNestablePublicClientApplication(msalConfig);\n    await msalInstance.initialize();\n\n    this._state = { phase: 'started', msalInstance, context, startedAt: new Date() };\n    this._log.debug('app started');\n  }\n\n  /**\n   * Execute a server-side function\n   * @param name The unique function name\n   * @param data The data to send\n   * @param options Options\n   * @param options.msalTokenRequest Optional MSAL token request.\n   * If omitted, a default token request is used.\n   * @param options.requestHeaders Optional additional request headers.\n   * @returns The function response\n   */\n  async exec<T = unknown>(name: string, data?: unknown, options?: ExecOptions): Promise<T> {\n    if (this._state.phase !== 'started') {\n      throw new Error('App not started');\n    }\n\n    const { context } = this._state;\n    const accessToken = await acquireMsalAccessToken(\n      this._state.msalInstance,\n      options?.msalTokenRequest ?? getStandardExecSilentRequest(this.clientId, options?.permission),\n      this._log\n    );\n\n    const res = await this.http.post<T>(`/api/functions/${name}`, data, {\n      headers: {\n        authorization: `Bearer ${accessToken}`,\n        'x-teams-app-session-id': context.app.sessionId,\n        'x-teams-channel-id': context.channel?.id,\n        'x-teams-chat-id': context.chat?.id,\n        'x-teams-meeting-id': context.meeting?.id,\n        'x-teams-message-id': context.app.parentMessageId,\n        'x-teams-page-id': context.page.id,\n        'x-teams-sub-page-id': context.page.subPageId,\n        'x-teams-team-id': context.team?.internalId,\n        ...(options?.requestHeaders ?? {}),\n      },\n    });\n\n    return res.data;\n  }\n}\n"]}

package/dist/context/app-host.d.mts

@@ -0,0 +1,25 @@
+import { HostName, HostClientType } from '../window/types/host.mjs';
+
+/**
+ * Represents information about the application's host.
+ */
+type AppHostContext = {
+    /**
+     * Identifies which host is running your app
+     */
+    name: HostName;
+    /**
+     * The client type on which the host is running
+     */
+    clientType: HostClientType;
+    /**
+     * Unique ID for the current Host session for use in correlating telemetry data.
+     */
+    sessionId: string;
+    /**
+     * Current ring ID
+     */
+    ringId?: string;
+};
+
+export type { AppHostContext };

package/dist/context/app-host.d.ts

@@ -0,0 +1,25 @@
+import { HostName, HostClientType } from '../window/types/host.js';
+
+/**
+ * Represents information about the application's host.
+ */
+type AppHostContext = {
+    /**
+     * Identifies which host is running your app
+     */
+    name: HostName;
+    /**
+     * The client type on which the host is running
+     */
+    clientType: HostClientType;
+    /**
+     * Unique ID for the current Host session for use in correlating telemetry data.
+     */
+    sessionId: string;
+    /**
+     * Current ring ID
+     */
+    ringId?: string;
+};
+
+export type { AppHostContext };

package/dist/context/app-host.js

@@ -0,0 +1,4 @@
+'use strict';
+
+//# sourceMappingURL=app-host.js.map
+//# sourceMappingURL=app-host.js.map

package/dist/context/app-host.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"app-host.js"}

package/dist/context/app-host.mjs

@@ -0,0 +1,3 @@
+
+//# sourceMappingURL=app-host.mjs.map
+//# sourceMappingURL=app-host.mjs.map

package/dist/context/app-host.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"app-host.mjs"}

package/dist/context/app.d.mts

@@ -0,0 +1,69 @@
+import { FileOpenPreference } from '../window/types/file-open-preference.mjs';
+import { Locale } from '../window/types/locale.mjs';
+import { Theme } from '../window/types/theme.mjs';
+import { AppHostContext } from './app-host.mjs';
+import '../window/types/host.mjs';
+
+/**
+ * Represents application information.
+ */
+type AppContext = {
+    /**
+     * This ID is the unique identifier assigned to the app after deployment and is critical for ensuring the correct app instance is recognized across hosts.
+     */
+    id?: string;
+    /**
+     * ID for the current visible app which is different for across cached sessions. Used for correlating telemetry data.
+     */
+    launchId?: string;
+    /**
+     * Unique ID for the current session for use in correlating telemetry data. A session corresponds to the lifecycle of an app. A new session begins upon the creation of a webview (on Teams mobile) or iframe (in Teams desktop) hosting the app, and ends when it is destroyed.
+     */
+    sessionId: string;
+    /**
+     * The current locale that the user has configured for the app formatted as
+     * languageId-countryId (for example, en-us).
+     */
+    locale: string;
+    /**
+     * The current UI theme of the host. Possible values: "default", "dark", "contrast" or "glass".
+     */
+    theme: Theme;
+    /**
+     * Info of the host
+     */
+    host: AppHostContext;
+    /**
+     * More detailed locale info from the user's OS if available. Can be used together with
+     * the @microsoft/globe NPM package to ensure your app respects the user's OS date and
+     * time format configuration
+     */
+    osLocaleInfo?: Locale;
+    /**
+     * Personal app icon y coordinate position
+     */
+    iconPositionVertical?: number;
+    /**
+     * Time when the user clicked on the tab using the date.
+     */
+    userClickTime?: number;
+    /**
+     * Time when the user click on the app by using the performance timer API. Useful for measuring elapsed time accurately.
+     */
+    userClickTimeV2?: number;
+    /**
+     * The ID of the parent message from which this task module was launched.
+     * This is only available in task modules launched from bot cards.
+     */
+    parentMessageId?: string;
+    /**
+     * Where the user prefers the file to be opened from by default during file open
+     */
+    userFileOpenPreference?: FileOpenPreference;
+    /**
+     * The version of the manifest that the app is running.
+     */
+    manifestVersion?: string;
+};
+
+export type { AppContext };