@microsoft/rayfin-functions 1.36.0-alpha.1675 → 1.36.0-alpha.1756

package/README.md

@@ -1,6 +1,6 @@
 # @microsoft/rayfin-functions
 
-> **Experimental** — this package is experimental and may change substantially in the near future.
+See the [SDK reference overview](./assets/docs/index.md) for the public API.
 
 ## Getting started
 

package/assets/docs/index.md

@@ -0,0 +1,60 @@
+---
+symbols:
+  - FunctionClient
+  - FunctionClient.invoke
+  - FunctionsError
+  - createFunctionsApi
+  - InvokeOptions
+  - FunctionInvocationResponse
+  - FunctionsSchema
+  - TypedFunctionClients
+---
+
+# @microsoft/rayfin-functions
+
+[![npm version](https://badge.fury.io/js/%40microsoft%2Frayfin-functions.svg)](https://badge.fury.io/js/%40microsoft%2Frayfin-functions)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.2+-blue.svg)](https://www.typescriptlang.org/)
+
+Type-safe client library for invoking Rayfin user-defined functions with strongly-typed inputs and outputs.
+Most applications access it through `client.functions.<name>.invoke()` on `RayfinClient`.
+This package invokes functions; server-side authoring belongs to `@microsoft/fabric-user-data-functions`.
+
+## Installation
+
+```bash
+npm install @microsoft/rayfin-functions
+```
+
+## API summary
+
+| Export | Purpose |
+| --- | --- |
+| `FunctionClient<TInput, TOutput>` | Client for one named function; constructed with `(apiClient, functionName)`. |
+| `FunctionsError` | Invocation error extending `SdkError`, with a message and error code. |
+| `createFunctionsApi<TSchema>(apiClient)` | Creates typed, lazily cached clients for the function names in a schema. |
+| `InvokeOptions` | Per-call `headers` and `timeoutMs` options. |
+| `FunctionInvocationResponse<TOutput>` | Transport envelope containing status, output, errors, and invocation ID; **not** the return type of `invoke()`. |
+| `FunctionsSchema` | Maps each function name to its `input` and `output` types. |
+| `TypedFunctionClients<TSchema>` | Maps a schema to its typed `FunctionClient` properties. |
+
+## Invocation contract
+
+`invoke(params, options?)` returns `Promise<TOutput>`: the output value directly, not an object with an `output` property.
+For a no-input function, use `invoke()` or `invoke(undefined, options)`.
+Options always occupy the second argument.
+
+`timeoutMs` defaults to 250,000 ms and is capped at that value.
+A positive, finite value below the cap shortens the timeout; other invalid values use the default.
+Extra request headers are supplied through `headers`.
+
+A non-success response or a non-empty `errors` array throws `FunctionsError` with code `FUNCTION_EXECUTION_ERROR`.
+Network and SDK errors propagate unchanged; unexpected errors use `UNKNOWN_FUNCTION_ERROR`.
+Schemas provide compile-time types, not runtime validation.
+
+## Guides
+
+See the [Functions guide](/docs/guide/functions/), [frontend invocation walkthrough](/docs/guide/functions/invoking-from-frontend), and [type generation guide](/docs/guide/functions/typegen) for how-to instructions.
+
+## License
+
+Copyright (c) Microsoft Corporation. Licensed under the MIT License.

package/dist/FunctionClient.d.ts

@@ -7,7 +7,8 @@
  */
 import { ApiClient } from '@microsoft/rayfin-lib';
 /**
- * Response from a function invocation.
+ * Transport response from a function invocation.
+ * `FunctionClient.invoke()` returns the output value, not this envelope.
  */
 export interface FunctionInvocationResponse<TOutput = any> {
     /** The name of the function that was invoked. */
@@ -75,10 +76,8 @@ export declare class FunctionClient<TInput = any, TOutput = any> {
      *
      * 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`.
+     * Network and other SDK errors propagate unchanged.
+     * Unexpected errors are wrapped in {@link FunctionsError}.
      *
      * The server-side `invocationId` from the underlying envelope is
      * emitted via `console.debug` (along with the function name) so the

package/dist/FunctionClient.js

@@ -55,10 +55,8 @@ export class FunctionClient {
      *
      * 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`.
+     * Network and other SDK errors propagate unchanged.
+     * Unexpected errors are wrapped in {@link FunctionsError}.
      *
      * The server-side `invocationId` from the underlying envelope is
      * emitted via `console.debug` (along with the function name) so the

package/dist/FunctionsSchema.d.ts

@@ -1,8 +1,8 @@
 /**
  * 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
+ * Users define a concrete schema type in their
+ * `rayfin/functions/src/types.ts` file, then pass it as the second type
  * parameter of `RayfinClient` so that `client.functions.<name>.invoke()`
  * calls are fully type-checked.
  *
@@ -10,13 +10,11 @@
  *
  * @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 };
  *   noParams: { input: void; output: string };  // use void or {} for no-input functions
- * } satisfies FunctionsSchema;
+ * };
  * ```
  */
 export type FunctionsSchema = Record<string, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/rayfin-functions",
-  "version": "1.36.0-alpha.1675",
+  "version": "1.36.0-alpha.1756",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -8,8 +8,15 @@
     "dist/**/*.js",
     "dist/**/*.d.ts",
     "!dist/**/__tests__/**",
-    "LICENSE"
+    "LICENSE",
+    "assets/docs"
   ],
+  "rayfinDocs": {
+    "version": 1,
+    "dir": "assets/docs",
+    "module": "rayfin-functions",
+    "kind": "api-reference"
+  },
   "devDependencies": {
     "eslint": "^9.28.0",
     "prettier": "^3.5.3",
@@ -19,7 +26,7 @@
     "rimraf": "~6.0.1"
   },
   "dependencies": {
-    "@microsoft/rayfin-lib": "1.36.0-alpha.1675"
+    "@microsoft/rayfin-lib": "1.36.0-alpha.1756"
   },
   "publishConfig": {
     "registry": "https://npm.pkg.github.com",