@microsoft/rayfin-functions 1.31.0 → 1.33.0-beta.0

package/dist/FunctionClient.d.ts

@@ -1,5 +1,5 @@
 /**
- * @fileoverview Per-function typed client.
+ * @packageDocumentation Per-function typed client.
  *
  * Each property on the proxy returned by `createFunctionsApi` is a
  * `FunctionClient` whose `invoke()` signature is derived from the schema
@@ -35,33 +35,48 @@ export interface InvokeOptions {
 /**
  * A strongly-typed client for a single function.
  *
- * @template TInput  - The parameter object the function expects (`void` when none).
- * @template TOutput - The type returned by the function.
+ * @typeParam TInput - The parameter object the function expects (`void` when none).
+ * @typeParam TOutput - The type returned by the function.
  */
 export declare class FunctionClient<TInput = any, TOutput = any> {
     private apiClient;
     private functionName;
     constructor(apiClient: ApiClient, functionName: string);
     /**
-     * Invoke the function.
+     * Invoke the function and return its typed output.
      *
-     * @param params   - Input parameters (omit when the function takes no input).
-     * @param options  - Optional per-call settings (extra headers, etc.).
-     * @returns A response whose `output` field is typed as `TOutput`.
+     * @param args - When the function accepts input, pass
+     *   `[params, options?]` — `params` are the input parameters declared
+     *   by the function schema, `options` are optional per-call settings
+     *   (extra headers, etc.). When the function takes no input, pass
+     *   `[options?]` instead.
+     * @returns The function's success-path output, typed as `TOutput`.
      *
-     * @throws {FunctionsError} If the function invocation fails.
-     * @throws {NetworkError}   For network-related issues.
-     * @throws {SdkError}       For any other unexpected SDK errors.
+     * Failure modes throw — a non-empty `errors` array or a non-success
+     * status on the wire response is surfaced as {@link FunctionsError}.
+     * Network and unknown errors are wrapped in {@link NetworkError} and
+     * {@link FunctionsError} respectively. By the time this method
+     * resolves, the caller can use the value without defending against
+     * `undefined`.
+     *
+     * The server-side `invocationId` from the underlying envelope is
+     * emitted via `console.debug` (along with the function name) so the
+     * value is available in the browser/Node console for correlation
+     * without polluting the public return type.
+     *
+     * @throws {@link FunctionsError} - If the function invocation fails.
+     * @throws `NetworkError` - For network-related issues.
+     * @throws `SdkError` - For any other unexpected SDK errors.
      *
      * @example
      * ```typescript
-     * const res = await client.functions.helloWorld.invoke({
+     * const greeting = await client.functions.helloWorld.invoke({
      *   firstName: 'Ada',
      *   lastName: 'Lovelace',
      * });
-     * console.log(res.output); // typed as string
+     * console.log(greeting); // typed as string
      * ```
      */
-    invoke(...args: TInput extends void ? [options?: InvokeOptions] : [params: TInput, options?: InvokeOptions]): Promise<FunctionInvocationResponse<TOutput>>;
+    invoke(...args: TInput extends void ? [options?: InvokeOptions] : [params: TInput, options?: InvokeOptions]): Promise<TOutput>;
 }
 //# sourceMappingURL=FunctionClient.d.ts.map

package/dist/FunctionClient.js

@@ -1,5 +1,5 @@
 /**
- * @fileoverview Per-function typed client.
+ * @packageDocumentation Per-function typed client.
  *
  * Each property on the proxy returned by `createFunctionsApi` is a
  * `FunctionClient` whose `invoke()` signature is derived from the schema
@@ -7,12 +7,12 @@
  */
 import { SdkError, NetworkError } from '@microsoft/rayfin-lib';
 import { FUNCTIONS_BASE_PATH } from '@microsoft/rayfin-lib';
-import { FunctionsError } from './Functions';
+import { FunctionsError } from './Functions.js';
 /**
  * A strongly-typed client for a single function.
  *
- * @template TInput  - The parameter object the function expects (`void` when none).
- * @template TOutput - The type returned by the function.
+ * @typeParam TInput - The parameter object the function expects (`void` when none).
+ * @typeParam TOutput - The type returned by the function.
  */
 export class FunctionClient {
     apiClient;
@@ -22,23 +22,38 @@ export class FunctionClient {
         this.functionName = functionName;
     }
     /**
-     * Invoke the function.
+     * Invoke the function and return its typed output.
      *
-     * @param params   - Input parameters (omit when the function takes no input).
-     * @param options  - Optional per-call settings (extra headers, etc.).
-     * @returns A response whose `output` field is typed as `TOutput`.
+     * @param args - When the function accepts input, pass
+     *   `[params, options?]` — `params` are the input parameters declared
+     *   by the function schema, `options` are optional per-call settings
+     *   (extra headers, etc.). When the function takes no input, pass
+     *   `[options?]` instead.
+     * @returns The function's success-path output, typed as `TOutput`.
      *
-     * @throws {FunctionsError} If the function invocation fails.
-     * @throws {NetworkError}   For network-related issues.
-     * @throws {SdkError}       For any other unexpected SDK errors.
+     * Failure modes throw — a non-empty `errors` array or a non-success
+     * status on the wire response is surfaced as {@link FunctionsError}.
+     * Network and unknown errors are wrapped in {@link NetworkError} and
+     * {@link FunctionsError} respectively. By the time this method
+     * resolves, the caller can use the value without defending against
+     * `undefined`.
+     *
+     * The server-side `invocationId` from the underlying envelope is
+     * emitted via `console.debug` (along with the function name) so the
+     * value is available in the browser/Node console for correlation
+     * without polluting the public return type.
+     *
+     * @throws {@link FunctionsError} - If the function invocation fails.
+     * @throws `NetworkError` - For network-related issues.
+     * @throws `SdkError` - For any other unexpected SDK errors.
      *
      * @example
      * ```typescript
-     * const res = await client.functions.helloWorld.invoke({
+     * const greeting = await client.functions.helloWorld.invoke({
      *   firstName: 'Ada',
      *   lastName: 'Lovelace',
      * });
-     * console.log(res.output); // typed as string
+     * console.log(greeting); // typed as string
      * ```
      */
     async invoke(...args) {
@@ -66,7 +81,16 @@ export class FunctionClient {
                 parameters = args[0];
                 options = args[1];
             }
-            const url = `${FUNCTIONS_BASE_PATH}/${this.functionName}/invoke`;
+            // When a `functionsBaseUrl` is configured on the ApiClient (e.g. by
+            // local-debug flows that point at a `func start` process), invoke the
+            // function directly against `${functionsBaseUrl}/api/<name>` using the
+            // Azure Functions Core Tools routing convention. Otherwise fall back to
+            // the production path `${baseUrl}/functions/<name>/invoke` handled by
+            // the Fabric `InvokeController`.
+            const functionsBaseUrl = this.apiClient.getFunctionsBaseUrl();
+            const url = functionsBaseUrl
+                ? `${functionsBaseUrl}/api/${this.functionName}`
+                : `${FUNCTIONS_BASE_PATH}/${this.functionName}/invoke`;
             const response = await this.apiClient.post(url, parameters ?? {}, { headers: options?.headers });
             // Check for errors in the response body
             if (response.errors && response.errors.length > 0) {
@@ -80,23 +104,39 @@ export class FunctionClient {
             if (status !== 'success' && status !== 'succeeded') {
                 throw new FunctionsError(`Function invocation failed with status: ${response.status}`, 'FUNCTION_EXECUTION_ERROR');
             }
-            // Auto-parse JSON-encoded output strings
+            // Auto-parse JSON-encoded output strings. The Fabric runtime
+            // sometimes wraps the user's return value in an inner envelope
+            // (a stringified `{ output: <value> }`); peel that off so the
+            // caller always sees the original `TOutput`.
+            // To-Do Investigate why the double JSON encoding is necessary on the runtime side and whether it can be eliminated.
+            let output;
             if (typeof response.output === 'string') {
                 try {
                     const parsed = JSON.parse(response.output);
-                    // If the parsed envelope has its own `output` field, unwrap it
                     if (parsed && typeof parsed === 'object' && 'output' in parsed) {
-                        response.output = parsed.output;
+                        output = parsed.output;
                     }
                     else {
-                        response.output = parsed;
+                        output = parsed;
                     }
                 }
                 catch {
-                    // Not JSON — leave as-is (TOutput may be `string`)
+                    // Not JSON — pass through (TOutput may be `string`)
+                    output = response.output;
                 }
             }
-            return response;
+            else {
+                output = response.output;
+            }
+            // Surface invocationId via console.debug so callers can correlate
+            // a UI action with server-side telemetry without us having to
+            // bake the envelope into the return type. This is opt-in noise
+            // that DevTools / Node consoles hide unless the verbose level is
+            // turned on.
+            if (response.invocationId) {
+                console.debug(`[rayfin-functions] ${this.functionName} invocationId=${response.invocationId}`);
+            }
+            return output;
         }
         catch (error) {
             if (error instanceof FunctionsError ||

package/dist/Functions.d.ts

@@ -1,5 +1,5 @@
 /**
- * @fileoverview Functions API for invoking serverless functions.
+ * @packageDocumentation Functions API for invoking serverless functions.
  *
  * The single public surface is `client.functions.<name>.invoke(...)` where
  * `<name>` is constrained by the `FunctionsSchema` type parameter passed to
@@ -10,10 +10,10 @@
  * ```
  */
 import { ApiClient, SdkError } from '@microsoft/rayfin-lib';
-import { FunctionClient } from './FunctionClient';
-import type { FunctionsSchema } from './FunctionsSchema';
-export { FunctionClient } from './FunctionClient';
-export type { FunctionInvocationResponse, InvokeOptions, } from './FunctionClient';
+import { FunctionClient } from './FunctionClient.js';
+import type { FunctionsSchema } from './FunctionsSchema.js';
+export { FunctionClient } from './FunctionClient.js';
+export type { FunctionInvocationResponse, InvokeOptions, } from './FunctionClient.js';
 /**
  * Functions error specific to the Rayfin SDK.
  */

package/dist/Functions.js

@@ -1,5 +1,5 @@
 /**
- * @fileoverview Functions API for invoking serverless functions.
+ * @packageDocumentation Functions API for invoking serverless functions.
  *
  * The single public surface is `client.functions.<name>.invoke(...)` where
  * `<name>` is constrained by the `FunctionsSchema` type parameter passed to
@@ -10,8 +10,8 @@
  * ```
  */
 import { SdkError } from '@microsoft/rayfin-lib';
-import { FunctionClient } from './FunctionClient';
-export { FunctionClient } from './FunctionClient';
+import { FunctionClient } from './FunctionClient.js';
+export { FunctionClient } from './FunctionClient.js';
 /**
  * Functions error specific to the Rayfin SDK.
  */

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { FunctionsError, createFunctionsApi, FunctionClient, } from './Functions';
-export type { FunctionInvocationResponse, InvokeOptions, TypedFunctionClients, } from './Functions';
-export type { FunctionsSchema } from './FunctionsSchema';
+export { FunctionsError, createFunctionsApi, FunctionClient, } from './Functions.js';
+export type { FunctionInvocationResponse, InvokeOptions, TypedFunctionClients, } from './Functions.js';
+export type { FunctionsSchema } from './FunctionsSchema.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,2 +1,2 @@
-export { FunctionsError, createFunctionsApi, FunctionClient, } from './Functions';
+export { FunctionsError, createFunctionsApi, FunctionClient, } from './Functions.js';
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/rayfin-functions",
-  "version": "1.31.0",
+  "version": "1.33.0-beta.0",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -19,7 +19,7 @@
     "rimraf": "~6.0.1"
   },
   "dependencies": {
-    "@microsoft/rayfin-lib": "1.31.0"
+    "@microsoft/rayfin-lib": "1.33.0-beta.0"
   },
   "publishConfig": {
     "registry": "https://npm.pkg.github.com",
@@ -35,7 +35,7 @@
   "license": "MIT",
   "type": "module",
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && node ../scripts/fix-esm-extensions.mjs ./dist",
     "build:watch": "tsc --watch",
     "clean": "rimraf dist && rimraf .tsbuildinfo",
     "test": "vitest run"