@microsoft/rayfin-functions 1.28.0 → 1.29.0

package/dist/FunctionClient.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @fileoverview Per-function typed client.
+ *
+ * Each property on the proxy returned by `createFunctionsApi` is a
+ * `FunctionClient` whose `invoke()` signature is derived from the schema
+ * entry for that function name.
+ */
+import { ApiClient } from '@microsoft/rayfin-lib';
+/**
+ * Response from a function invocation.
+ */
+export interface FunctionInvocationResponse<TOutput = any> {
+    /** The name of the function that was invoked. */
+    functionName: string;
+    /** A unique identifier for this invocation. */
+    invocationId: string;
+    /** Status of the function invocation (Success, Failed, etc.) */
+    status: string;
+    /**
+     * The output from the function.
+     * When the raw response contains a JSON-encoded string, `invoke()` auto-parses it
+     * so the caller receives `TOutput` directly.
+     */
+    output: TOutput;
+    /** Any errors that occurred during the function invocation. */
+    errors: Array<string | Record<string, any>>;
+}
+/**
+ * Options that can be supplied to a single `invoke()` call.
+ */
+export interface InvokeOptions {
+    /** Extra headers to attach to the request. */
+    headers?: Record<string, string>;
+}
+/**
+ * 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.
+ */
+export declare class FunctionClient<TInput = any, TOutput = any> {
+    private apiClient;
+    private functionName;
+    constructor(apiClient: ApiClient, functionName: string);
+    /**
+     * Invoke the function.
+     *
+     * @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`.
+     *
+     * @throws {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({
+     *   firstName: 'Ada',
+     *   lastName: 'Lovelace',
+     * });
+     * console.log(res.output); // typed as string
+     * ```
+     */
+    invoke(...args: TInput extends void ? [options?: InvokeOptions] : [params: TInput, options?: InvokeOptions]): Promise<FunctionInvocationResponse<TOutput>>;
+}
+//# sourceMappingURL=FunctionClient.d.ts.map

package/dist/FunctionClient.js

@@ -0,0 +1,111 @@
+/**
+ * @fileoverview Per-function typed client.
+ *
+ * Each property on the proxy returned by `createFunctionsApi` is a
+ * `FunctionClient` whose `invoke()` signature is derived from the schema
+ * entry for that function name.
+ */
+import { SdkError, NetworkError } from '@microsoft/rayfin-lib';
+import { FUNCTIONS_BASE_PATH } from '@microsoft/rayfin-lib';
+import { FunctionsError } from './Functions';
+/**
+ * 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.
+ */
+export class FunctionClient {
+    apiClient;
+    functionName;
+    constructor(apiClient, functionName) {
+        this.apiClient = apiClient;
+        this.functionName = functionName;
+    }
+    /**
+     * Invoke the function.
+     *
+     * @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`.
+     *
+     * @throws {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({
+     *   firstName: 'Ada',
+     *   lastName: 'Lovelace',
+     * });
+     * console.log(res.output); // typed as string
+     * ```
+     */
+    async invoke(...args) {
+        try {
+            // Unpack the variadic args – when TInput is void the first arg is options.
+            let parameters;
+            let options;
+            if (args.length === 0) {
+                // No-arg call: `fn.invoke()`
+            }
+            else if (args.length === 1) {
+                // Could be `invoke(params)` or `invoke(options)` for void-input fns
+                const first = args[0];
+                if (first &&
+                    typeof first === 'object' &&
+                    'headers' in first &&
+                    Object.keys(first).every((k) => k === 'headers')) {
+                    options = first;
+                }
+                else {
+                    parameters = first;
+                }
+            }
+            else {
+                parameters = args[0];
+                options = args[1];
+            }
+            const url = `${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) {
+                const errorMessage = typeof response.errors[0] === 'string'
+                    ? response.errors[0]
+                    : JSON.stringify(response.errors[0]);
+                throw new FunctionsError(`Function invocation failed: ${errorMessage}`, 'FUNCTION_EXECUTION_ERROR');
+            }
+            // Check for failed status
+            const status = response.status.toLowerCase();
+            if (status !== 'success' && status !== 'succeeded') {
+                throw new FunctionsError(`Function invocation failed with status: ${response.status}`, 'FUNCTION_EXECUTION_ERROR');
+            }
+            // Auto-parse JSON-encoded output strings
+            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;
+                    }
+                    else {
+                        response.output = parsed;
+                    }
+                }
+                catch {
+                    // Not JSON — leave as-is (TOutput may be `string`)
+                }
+            }
+            return response;
+        }
+        catch (error) {
+            if (error instanceof FunctionsError ||
+                error instanceof NetworkError ||
+                error instanceof SdkError) {
+                throw error;
+            }
+            throw new FunctionsError(`An unexpected error occurred during function invocation: ${error.message || error}`, 'UNKNOWN_FUNCTION_ERROR');
+        }
+    }
+}
+//# sourceMappingURL=FunctionClient.js.map

package/dist/Functions.d.ts

@@ -1,8 +1,19 @@
 /**
- * @fileoverview Functions API client for invoking serverless functions.
- * This file provides an API for invoking serverless functions through the Rayfin platform.
+ * @fileoverview 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
+ * `RayfinClient`.
+ *
+ * ```ts
+ * const res = await client.functions.helloWorld.invoke({ firstName: 'Ada' });
+ * ```
  */
-import { ApiClient, SdkError, NetworkError } from '@microsoft/rayfin-lib';
+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';
 /**
  * Functions error specific to the Rayfin SDK.
  */
@@ -10,99 +21,23 @@ export declare class FunctionsError extends SdkError {
     constructor(message: string, code?: string);
 }
 /**
- * Parameters for a function invocation request.
+ * Mapped type that produces one `FunctionClient` property per schema entry.
+ *
+ * `client.functions` resolves to this type — every key in `TSchema` becomes
+ * a strongly-typed per-function client whose `invoke()` signature matches
+ * the schema entry.
  */
-export interface FunctionInvocationParams {
-    /**
-     * The name of the function to invoke.
-     */
-    functionName: string;
-    /**
-     * Optional parameters to pass to the function.
-     */
-    parameters?: Record<string, any>;
-    /**
-     * Optional headers to include with the invocation request.
-     */
-    headers?: Record<string, string>;
-}
+export type TypedFunctionClients<TSchema extends FunctionsSchema> = {
+    [K in keyof TSchema & string]: FunctionClient<TSchema[K]['input'], TSchema[K]['output']>;
+};
 /**
- * Response from a function invocation.
+ * Create a typed `client.functions` proxy that lazily instantiates and caches
+ * a {@link FunctionClient} per schema-defined function name.
+ *
+ * ```ts
+ * const fns = createFunctionsApi<MyFunctionsSchema>(apiClient);
+ * const res = await fns.helloWorld.invoke({ firstName: 'Ada' });
+ * ```
  */
-export interface FunctionInvocationResponse<T = any> {
-    /**
-     * The name of the function that was invoked.
-     */
-    functionName: string;
-    /**
-     * A unique identifier for this invocation.
-     */
-    invocationId: string;
-    /**
-     * Status of the function invocation (Success, Failed, etc.)
-     */
-    status: string;
-    /**
-     * The output from the function. This can be a string containing JSON or any other data.
-     * When it's a JSON string, it will typically have its own nested structure with functionName,
-     * invocationId, status, output, and errors fields.
-     */
-    output: string | T;
-    /**
-     * Any errors that occurred during the function invocation.
-     */
-    errors: Array<string | Record<string, any>>;
-}
-/**
- * Main Functions class for Rayfin.
- * This class provides the high-level API for invoking serverless functions.
- */
-export declare class FunctionsApi {
-    private apiClient;
-    static readonly errors: {
-        FunctionsError: typeof FunctionsError;
-        NetworkError: typeof NetworkError;
-        SdkError: typeof SdkError;
-    };
-    /**
-     * @param apiClient An instance of ApiClient to be used for API requests.
-     */
-    constructor(apiClient: ApiClient);
-    /**
-     * Helper method to parse the output field of a function response when it contains a JSON string.
-     *
-     * @param response The function invocation response
-     * @returns The parsed output object, or the original output if it's not valid JSON
-     */
-    parseOutput<T = any, R = any>(response: FunctionInvocationResponse<T>): R | string | T;
-    /**
-     * Invokes a serverless function with the given parameters.
-     *
-     * @param params The function invocation parameters
-     * @returns A promise that resolves with the function invocation response
-     * @throws {FunctionsError} If the function invocation fails
-     * @throws {NetworkError} For network-related issues
-     * @throws {SdkError} For any other unexpected SDK errors
-     *
-     * @example
-     * ```typescript
-     * const response = await functions.invoke({
-     *   functionName: 'processOrder',
-     *   parameters: {
-     *     orderId: '12345',
-     *     amount: 99.99
-     *   }
-     * });
-     *
-     * // Direct access to the response
-     * console.log(response.status);
-     * console.log(response.invocationId);
-     *
-     * // Parse the output field if it contains JSON
-     * const parsedOutput = functions.parseOutput(response);
-     * console.log(parsedOutput); // Will contain the actual result
-     * ```
-     */
-    invoke<T = any>(params: FunctionInvocationParams): Promise<FunctionInvocationResponse<T>>;
-}
+export declare function createFunctionsApi<TSchema extends FunctionsSchema = FunctionsSchema>(apiClient: ApiClient): TypedFunctionClients<TSchema>;
 //# sourceMappingURL=Functions.d.ts.map

package/dist/Functions.js

@@ -1,9 +1,17 @@
 /**
- * @fileoverview Functions API client for invoking serverless functions.
- * This file provides an API for invoking serverless functions through the Rayfin platform.
+ * @fileoverview 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
+ * `RayfinClient`.
+ *
+ * ```ts
+ * const res = await client.functions.helloWorld.invoke({ firstName: 'Ada' });
+ * ```
  */
-import { SdkError, NetworkError } from '@microsoft/rayfin-lib';
-import { FUNCTIONS_INVOKE_PATH } from '@microsoft/rayfin-lib';
+import { SdkError } from '@microsoft/rayfin-lib';
+import { FunctionClient } from './FunctionClient';
+export { FunctionClient } from './FunctionClient';
 /**
  * Functions error specific to the Rayfin SDK.
  */
@@ -13,117 +21,45 @@ export class FunctionsError extends SdkError {
     }
 }
 /**
- * Main Functions class for Rayfin.
- * This class provides the high-level API for invoking serverless functions.
+ * Create a typed `client.functions` proxy that lazily instantiates and caches
+ * a {@link FunctionClient} per schema-defined function name.
+ *
+ * ```ts
+ * const fns = createFunctionsApi<MyFunctionsSchema>(apiClient);
+ * const res = await fns.helloWorld.invoke({ firstName: 'Ada' });
+ * ```
  */
-export class FunctionsApi {
-    apiClient;
-    // Static access to custom errors for easy import by consumers
-    static errors = {
-        FunctionsError,
-        NetworkError,
-        SdkError,
-    };
-    /**
-     * @param apiClient An instance of ApiClient to be used for API requests.
-     */
-    constructor(apiClient) {
-        this.apiClient = apiClient;
-    }
-    /**
-     * Helper method to parse the output field of a function response when it contains a JSON string.
-     *
-     * @param response The function invocation response
-     * @returns The parsed output object, or the original output if it's not valid JSON
-     */
-    parseOutput(response) {
-        if (typeof response.output === 'string') {
-            try {
-                // Try to parse the output as JSON
-                const parsedOutput = JSON.parse(response.output);
-                // If the parsed output has its own 'output' field, return that
-                if (parsedOutput &&
-                    typeof parsedOutput === 'object' &&
-                    'output' in parsedOutput) {
-                    return parsedOutput.output;
-                }
-                // Otherwise return the entire parsed object
-                return parsedOutput;
-            }
-            catch (e) {
-                // If parsing fails, return the original string
-                return response.output;
-            }
+export function createFunctionsApi(apiClient) {
+    const cache = new Map();
+    const get = (name) => {
+        let client = cache.get(name);
+        if (!client) {
+            client = new FunctionClient(apiClient, name);
+            cache.set(name, client);
         }
-        // If output is not a string, return it as is
-        return response.output;
-    }
-    /**
-     * Invokes a serverless function with the given parameters.
-     *
-     * @param params The function invocation parameters
-     * @returns A promise that resolves with the function invocation response
-     * @throws {FunctionsError} If the function invocation fails
-     * @throws {NetworkError} For network-related issues
-     * @throws {SdkError} For any other unexpected SDK errors
-     *
-     * @example
-     * ```typescript
-     * const response = await functions.invoke({
-     *   functionName: 'processOrder',
-     *   parameters: {
-     *     orderId: '12345',
-     *     amount: 99.99
-     *   }
-     * });
-     *
-     * // Direct access to the response
-     * console.log(response.status);
-     * console.log(response.invocationId);
-     *
-     * // Parse the output field if it contains JSON
-     * const parsedOutput = functions.parseOutput(response);
-     * console.log(parsedOutput); // Will contain the actual result
-     * ```
-     */
-    async invoke(params) {
-        try {
-            // Basic validation
-            if (!params.functionName) {
-                throw new FunctionsError('Function name is required for invocation', 'MISSING_FUNCTION_NAME');
-            }
-            const { functionName, parameters, headers } = params;
-            // Prepare the request payload
-            const payload = {
-                functionName,
-                parameters: parameters || {},
+        return client;
+    };
+    return new Proxy(Object.create(null), {
+        get(_target, prop) {
+            if (typeof prop !== 'string')
+                return undefined;
+            return get(prop);
+        },
+        has(_target, prop) {
+            return typeof prop === 'string';
+        },
+        ownKeys() {
+            return Array.from(cache.keys());
+        },
+        getOwnPropertyDescriptor(_target, prop) {
+            if (typeof prop !== 'string')
+                return undefined;
+            return {
+                enumerable: true,
+                configurable: true,
+                value: get(prop),
             };
-            // Make the POST request to the functions/invoke endpoint
-            const response = await this.apiClient.post(FUNCTIONS_INVOKE_PATH, payload, { headers });
-            // Check for function errors in the response
-            if (response.errors && response.errors.length > 0) {
-                const errorMessage = typeof response.errors[0] === 'string'
-                    ? response.errors[0]
-                    : JSON.stringify(response.errors[0]);
-                throw new FunctionsError(`Function invocation failed: ${errorMessage}`, 'FUNCTION_EXECUTION_ERROR');
-            }
-            // Check for failed status
-            if (response.status.toLowerCase() !== 'success' &&
-                response.status.toLowerCase() !== 'succeeded') {
-                throw new FunctionsError(`Function invocation failed with status: ${response.status}`, 'FUNCTION_EXECUTION_ERROR');
-            }
-            return response;
-        }
-        catch (error) {
-            // Re-throw specific SDK errors
-            if (error instanceof FunctionsError ||
-                error instanceof NetworkError ||
-                error instanceof SdkError) {
-                throw error;
-            }
-            // Wrap other errors in a FunctionsError
-            throw new FunctionsError(`An unexpected error occurred during function invocation: ${error.message || error}`, 'UNKNOWN_FUNCTION_ERROR');
-        }
-    }
+        },
+    });
 }
 //# sourceMappingURL=Functions.js.map

package/dist/FunctionsSchema.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Maps function names to their input/output type pairs.
+ *
+ * Users define a concrete type that `satisfies FunctionsSchema` in their
+ * `rayfin/functions/src/types.ts` file, then pass it as the third type
+ * parameter of `RayfinClient` so that `client.functions.<name>.invoke()`
+ * calls are fully type-checked.
+ *
+ * Use an object type for named params, or `void` for no params.
+ *
+ * @example
+ * ```typescript
+ * import type { FunctionsSchema } from '@microsoft/rayfin-functions';
+ *
+ * export type MyFunctionsSchema = {
+ *   helloWorld: { input: { firstName: string; lastName: string }; output: string };
+ *   add: { input: { a: number; b: number }; output: number };
+ * } satisfies FunctionsSchema;
+ * ```
+ */
+export type FunctionsSchema = Record<string, {
+    input: any;
+    output: any;
+}>;
+//# sourceMappingURL=FunctionsSchema.d.ts.map

package/dist/FunctionsSchema.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=FunctionsSchema.js.map

package/dist/index.d.ts

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

package/dist/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/rayfin-functions",
-  "version": "1.28.0",
+  "version": "1.29.0",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -19,7 +19,7 @@
     "rimraf": "~6.0.1"
   },
   "dependencies": {
-    "@microsoft/rayfin-lib": "1.28.0"
+    "@microsoft/rayfin-lib": "1.29.0"
   },
   "publishConfig": {
     "registry": "https://npm.pkg.github.com",