@uipath/skills 1.201.0-preview.621 → 1.202.0-preview.635

package/skills/uipath-functions/references/js/bindings-guide.md

@@ -0,0 +1,120 @@
+# Bindings and Generated Descriptors
+
+How `uip function pack`/`push` generate `entry-points.json` and `bindings_v2.json`, how hand-added resource bindings survive regeneration, and how bound resources reach the SDK at runtime via resource overwrites.
+
+## Generated files
+
+`uip function pack` and `uip function push` (and `uip solution pack`, which packs in-process) regenerate two descriptors at the project root; pack then copies them into `content/` inside the `.nupkg`:
+
+| File | Contents |
+|---|---|
+| `entry-points.json` | One entry per function (the job surface) |
+| `bindings_v2.json` | One `HttpTrigger` resource per HTTP-exposed function + any hand-added resource bindings |
+| `package-descriptor.json` | Pack-time only; maps logical names to package paths — notably `"bindings.json"` → `"content/bindings_v2.json"` |
+
+Regeneration reconciles against the existing files instead of rewriting them. Do not delete `entry-points.json` or `bindings_v2.json` between packs: they are the baseline that keeps IDs stable and preserves hand-added resources.
+
+## entry-points.json
+
+One entry per `defineFunction`:
+
+```json
+{
+  "$schema": "https://cloud.uipath.com/draft/2024-12/entry-point",
+  "$id": "entry-points.json",
+  "entryPoints": [
+    {
+      "filePath": "content/functions/hello.ts",
+      "uniqueId": "<STABLE_UUID>",
+      "type": "function",
+      "input":  { "type": "object", "properties": { "name": { "type": "string" } } },
+      "output": { "type": "object", "properties": { "message": { "type": "string" } } }
+    }
+  ]
+}
+```
+
+Reconciliation rules on regeneration:
+
+- Function entries are matched by `filePath`: a match keeps its `uniqueId` (stable across re-packs, so Orchestrator updates triggers in place instead of duplicating) and keeps a manually-set `"isTransactionRoot": true`.
+- `input`/`output` are always re-derived from the function's declared schemas.
+- Entries whose function no longer exists are dropped.
+- Entries with `type` other than `"function"` are preserved verbatim (Studio Web or other tooling may write these).
+
+## bindings_v2.json — HttpTrigger resources
+
+Each function that declares `method` + `path` gets one `HttpTrigger` resource; job-only functions get none.
+
+```json
+{
+  "$schema": "https://cloud.uipath.com/draft/2024-12/bindings",
+  "version": "2.0",
+  "resources": [
+    {
+      "resource": "HttpTrigger",
+      "key": "<STABLE_UUID>",
+      "id": "<STABLE_UUID>",
+      "value": {
+        "EntryPointUniqueId": { "DefaultValue": "<ENTRY_POINT_UNIQUE_ID>", "IsExpression": false }
+      },
+      "metadata": {
+        "BindingsVersion": "2.1",
+        "Name": "hello",
+        "Method": "POST",
+        "Slug": "/hello",
+        "CallingMode": "LongPolling",
+        "Description": "Returns a greeting."
+      }
+    }
+  ]
+}
+```
+
+- Trigger identity is `Method` + `Slug`: an existing trigger matching both keeps its `key`/`id` across re-packs. The metadata `Slug` stores the `defineFunction` `path` verbatim — leading `/` included — unlike the invoke-URL segment, which drops it ([http-semantics-guide.md](http-semantics-guide.md)).
+- `CallingMode` is always `LongPolling` — synchronous long-polling; there is no async/fire-and-forget mode. The trigger account is always "Run as HTTP Caller": the request runs with the caller's identity as `ctx.user` (the robot identity is separate — see [calling-uipath-apis-guide.md](calling-uipath-apis-guide.md)).
+- `value.EntryPointUniqueId.DefaultValue` cross-references the function's `entry-points.json` `uniqueId`.
+
+### Lifecycle on re-pack + publish
+
+Orchestrator syncs triggers from these files after the Function Release is updated (manual step — see [deployment-guide.md](deployment-guide.md)):
+
+| Change in code | Effect after release update |
+|---|---|
+| New `defineFunction` | New entry point + binding → new HTTP trigger |
+| Renamed `name` or `path` | Old trigger deleted, new one created — **existing callers' URLs break** |
+| Removed function | Trigger deleted |
+| Changed `input`/`output` schema | Trigger schemas updated in place |
+
+Sharp edge: a rename is a delete+create, never an update. Treat `method` + `path` as a published contract.
+
+## Declaring resource bindings by hand
+
+Any resource whose `resource` field is not `"HttpTrigger"` is preserved **verbatim** across every regeneration — the generator never reads, validates, or rewrites it. That is the mechanism for binding platform resources (storage buckets, queues, assets, processes) to the package: add the entry to `resources[]` in `bindings_v2.json` by hand and it survives all future packs.
+
+Entry shape (`value` and `metadata` optional, passed through untouched):
+
+```json
+{
+  "resource": "Storage",
+  "key": "<UUID_YOU_MINT_ONCE>",
+  "id": "<UUID_YOU_MINT_ONCE>",
+  "metadata": { "Name": "blobs" }
+}
+```
+
+The per-resource-type `value`/`metadata` schemas are defined by the platform's binding surface (solution/Orchestrator side), not by this project's tooling — mirror an entry created by the platform for the target resource type rather than inventing fields.
+
+## Resource overwrites at runtime
+
+Resource bindings pay off at runtime as **resource overwrites**: Orchestrator resolves the bindings for the release and the robot's user into a table `{"<RESOURCE_TYPE>.<RESOURCE_KEY>": { <PROPERTY>: <VALUE> }}` (keys case-sensitive, passed through verbatim — placeholder casing is illustrative) and delivers it per invocation:
+
+- **HTTP mode**: request header `X-UiPath-ResourceOverwrites` (base64-encoded UTF-8 JSON), scoped to that one request. Never cached across requests — concurrent requests in one pooled process can belong to different releases/robot users.
+- **Job mode**: the `resourceOverwrites` field of `runtime-context.json` (see [job-mode-guide.md](job-mode-guide.md)).
+
+The runtime publishes an accessor at `globalThis[Symbol.for("uipath.resourceOverwrites.v1")]`; `@uipath/uipath-typescript` probes that slot and redirects its resource lookups (asset/queue/bucket/process names) to the bound targets. Nothing is surfaced on `ctx`, and function code needs no change.
+
+Behavior to rely on:
+
+- **Degrades, never fails**: an absent or corrupt header/table means SDK lookups fall back to the literal names written in code — a bindings problem never faults the invocation. The flip side: a broken binding manifests as "reads the wrong/original resource", not as an error.
+- **Local serve has no overwrites** unless the caller sets the header itself; lookups use literal names.
+- **When to care**: only when a function reads Assets/Buckets/Queues/Processes through `@uipath/uipath-typescript` and the deployment remaps them per environment or folder. Folder-correct redirection requires the whole chain: a hand-added resource entry in `bindings_v2.json` + the platform resolving it into the overwrite table for that release.

package/skills/uipath-functions/references/js/calling-uipath-apis-guide.md

@@ -0,0 +1,112 @@
+# Calling UiPath APIs from a Function
+
+Calling UiPath platform APIs from inside a function handler: which token to send, where platform coordinates come from, `@uipath/uipath-typescript` patterns for Orchestrator, and the working route to Integration Service connectors.
+
+## Token Decision
+
+[SKILL.md](../../SKILL.md) JS Rule 8 names the two identities; the decision rule:
+
+| Token | Identity | Use for |
+|---|---|---|
+| `ctx.user.accessToken` | The caller — delegated OAuth token from the request's `Authorization` header; the caller's folder permissions apply | Default: anything done on the caller's behalf |
+| `ctx.robot.accessToken` | The function's own serverless-robot identity — platform-issued RS256 robot JWT, ~24h TTL | Privileged/S2S reads the caller must not be able to do |
+
+Under local serve `ctx.robot` is always null ([local-dev-guide.md](local-dev-guide.md)); `ctx.user` is null only when the request carries no decodable Bearer JWT — serve decodes the `Authorization` header locally too. Privileged paths fall back robot-first to the env token:
+
+```typescript
+const token = ctx.robot?.accessToken || process.env["UIPATH_ACCESS_TOKEN"] || "";
+if (!token) throw new FunctionError("Robot token unavailable — local dev: set UIPATH_ACCESS_TOKEN", 500);
+```
+
+Delegated paths must require the caller token — never fall through to the robot identity, that silently escalates privileges:
+
+```typescript
+if (!ctx.user?.accessToken) throw new FunctionError("User access token not available", 401);
+```
+
+`ctx.robot.key` is the serverless robot's key — required by Orchestrator's per-robot endpoints, notably `GetRobotAssetByNameForRobotKey`.
+
+## Platform Coordinates
+
+Read `baseUrl`/`orgId`/`tenantId`/`folderKey` from `ctx.platform`, never from input — caller-forwarded `_baseUrl`/`_orgId`/`_tenantId` fields are deprecated because caller-controlled values redirect the function's platform calls. Env vars (`UIPATH_BASE_URL`/`UIPATH_ORG_ID`/`UIPATH_TENANT_ID`) are the local-only fallback that populates `ctx.platform` under serve ([local-dev-guide](local-dev-guide.md)).
+
+```typescript
+if (!ctx.platform) throw new FunctionError("Platform context unavailable — local dev: set UIPATH_BASE_URL/UIPATH_ORG_ID/UIPATH_TENANT_ID", 500);
+const { baseUrl, orgId, tenantId } = ctx.platform;
+```
+
+## Using @uipath/uipath-typescript
+
+Constructor maps ctx fields by these exact names; `initialize()` is a no-op in secret mode but call it anyway:
+
+```typescript
+import { UiPath } from "@uipath/uipath-typescript/core";
+import { Assets } from "@uipath/uipath-typescript/assets";
+
+const sdk = new UiPath({ baseUrl, orgName: orgId, tenantName: tenantId, secret: token });
+await sdk.initialize();
+```
+
+- The package goes in `dependencies` (public npm) — the SDK-placement and lockfile rules in [deployment-guide](deployment-guide.md) apply to it like any runtime dep.
+- The SDK auto-probes runtime-published resource overwrites — solution-managed resource names redirect transparently, no code needed ([bindings-guide](bindings-guide.md)).
+
+### Reading assets
+
+```typescript
+const escaped = input.assetName.replace(/'/g, "''");
+const res = await new Assets(sdk).getAll({ filter: `Name eq '${escaped}'`, folderId: input.folderId });
+return { value: res.items[0]?.value ?? null };
+```
+
+1. **`folderId` is required.** Without it `getAll` calls `GetAssetsAcrossFolders` (metadata only) and silently returns `null` for every value field.
+2. **OData string/GUID literals take single quotes**, embedded quotes escaped as `''`. An unquoted GUID → `400 Bad Request`, often surfacing as an empty list.
+3. **Secret-typed asset values are released only by `GetRobotAssetByNameForRobotKey`** (per-robot endpoint, takes `ctx.robot.key`) — `getAll` never returns them.
+4. `AllowDirectApiAccess` is irrelevant for OData endpoints — do not add it to the Orchestrator setup.
+
+### Secret Vault pattern (privileged read)
+
+For credentials/API keys the caller must never see: create a dedicated folder (e.g. `Restricted-Secrets`), grant the function's runtime service account (Orchestrator → Robots/Machines) **Assets.View** on that folder only, give callers zero access to it, and read with `ctx.robot.accessToken`. Non-sensitive assets: delegated token; the caller needs Assets.View on the folder. Folder RBAC, not the function layer, is the effective security boundary — rationale → [coded-app-wiring-guide.md](coded-app-wiring-guide.md).
+
+### Starting jobs
+
+```typescript
+import { Processes } from "@uipath/uipath-typescript/processes";
+
+const results = await new Processes(sdk).start(
+  { processKey: releaseKey, inputArguments: JSON.stringify(args), strategy: "ModernJobsCount", jobsCount: 1 },
+  folderId,   // numeric folder ID — sets X-UIPATH-OrganizationUnitId
+);
+return { jobId: results?.[0]?.id ?? null };
+```
+
+`processKey` takes the ReleaseKey UUID from `/odata/Releases`. When later listing jobs that may span folders (`GET /odata/Jobs`), omit `X-UIPATH-OrganizationUnitId` — without the header Orchestrator searches all accessible folders.
+
+## Integration Service Connectors
+
+Known sharp edge: no published SDK reaches Integration Service from inside a function. `@uipath/integrationservice-sdk` authenticates only from a `uip login` session (it cannot consume a ctx token) and `@uipath/uipath-typescript` has no Integration Service surface. The currently-working approach is the connector HTTP passthrough, called with a ctx token (same token decision as above; verified with the caller's delegated token):
+
+```typescript
+const res = await fetch(`${baseUrl}/${orgId}/${tenantId}/elements_/v3/element/instances/<CONNECTION_ID>/http-request`, {
+  method: "POST",
+  headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+  body: JSON.stringify({
+    authentication: "connector",
+    targetConnector: "<CONNECTOR_KEY>",   // e.g. "uipath-salesforce-slack"
+    method: "GET",
+    path: "/api/endpoint",
+    url: "/api/endpoint",
+    query: { param: "value" },
+  }),
+  signal: AbortSignal.timeout(8_000),
+});
+const envelope = await res.json();
+const downstream = Number(envelope.code ?? envelope.statusCode ?? res.status);
+if (downstream >= 400) throw new FunctionError(`Connector call failed (${downstream})`, downstream);
+```
+
+1. **Never trust the 200 wrapper.** The passthrough can answer `200` while the downstream call failed — read the downstream status from the response envelope (`code`/`statusCode`) and surface 4xx/5xx as `FunctionError` carrying that status.
+2. `<CONNECTION_ID>` is the Integration Service connection instance id; `<CONNECTOR_KEY>` is the connector key. Both are deployment configuration — resolve them per environment, do not hardcode tenant-specific ids in shared code.
+
+## Timeout Budget
+
+Every external call gets an `AbortSignal.timeout(...)` sized to the caller's budget — a browser-invoked function must finish under ~20 s total, so per-call timeouts of ~8 s leave room for retries and the response ([http-semantics-guide](http-semantics-guide.md)). A `403` on the function's own trigger (before the handler runs) usually means the caller's PKCE scope is missing `OR.Default` ([coded-app-wiring-guide](coded-app-wiring-guide.md)).

package/skills/uipath-functions/references/js/coded-app-wiring-guide.md

@@ -0,0 +1,103 @@
+# Coded App Wiring Guide
+
+Architecture and mechanics of the Coded App (frontend) ↔ JS function (backend) pairing: when a function belongs between the app and the platform, token flow, the two-server local loop, deployed calls, timeout budget, and the error contract the frontend codes against. The app side itself (scaffolding, PKCE registration, app deploy) → `uipath-coded-apps`.
+
+## When to Put a Function Between the App and the Platform
+
+Default: the app calls UiPath APIs directly with `@uipath/uipath-typescript` and the user's PKCE token. Add a function backend when any of these apply:
+
+| Reason | Why a function |
+|---|---|
+| Credentials / API keys / secrets | Must exist server-side only — browser code and its network tab are public. Secret Vault pattern → [calling-uipath-apis-guide.md](calling-uipath-apis-guide.md) |
+| S2S calls to third-party systems | Third-party credentials come from the vault via the function's robot identity — never a browser-held key |
+| Audit / tracing of privileged operations | Server-side `logger.*` lands in job logs; browser-side logging is unverifiable |
+| Heavy / multi-call orchestration | One browser round-trip; N platform calls server-side, inside the timeout budget |
+| Hiding internal API shapes | Function exposes a minimal stable contract; OData filters, folder IDs, endpoint quirks stay server-side |
+
+**Honest boundary:** a function in front of *delegated* calls is not a security layer. The caller's `OR.Default` PKCE token already grants broad Orchestrator API access — anything the function does with `ctx.user.accessToken`, the browser could do directly with the same token. Folder RBAC, not the function layer, is the effective security boundary for delegated calls. A function only *adds* privilege through its own robot identity (`ctx.robot`, Secret Vault pattern → [calling-uipath-apis-guide.md](calling-uipath-apis-guide.md)).
+
+## Token Flow
+
+The app sends its PKCE access token on every function call:
+
+```ts
+headers: { Authorization: `Bearer ${token}` }
+```
+
+Deployed, it arrives as `ctx.user.accessToken` — delegated identity, the caller's folder permissions apply. The app's PKCE scope string MUST include `OR.Default` explicitly; it is auto-granted to any registered External App but is not implicit in the scope string, and omitting it makes the deployed trigger return 403:
+
+```text
+openid profile email offline_access OR.Default
+```
+
+## Local Dev Loop
+
+Two terminals, no proxy:
+
+```bash
+uip function serve    # terminal 1 — functions on :7070, hot reload
+npm run dev           # terminal 2 — app dev server (Vite, :5173)
+```
+
+1. The app fetches `http://localhost:7070/<PATH>` directly — `serve` answers with CORS `Access-Control-Allow-Origin: *`, so the cross-port call works as-is.
+2. Do NOT add `server.proxy` to the app's Vite config to reach the function — it breaks the app's OAuth callback (hard rule in the coded-apps guidance → `uipath-coded-apps`).
+3. `serve` decodes `ctx.user` from a forwarded Bearer JWT when the app sends one (decoded, not verified — dev convenience only); an unauthenticated call (plain curl) gets `ctx.user = null`. `ctx.robot` / `ctx.platform` local values and env fallbacks → [local-dev-guide.md](local-dev-guide.md).
+
+## Deployed Calls from the App
+
+```ts
+const FN_BASE = import.meta.env.DEV
+  ? "http://localhost:7070"
+  : "https://api.<HOST>/<ORG_ID>/<TENANT_ID>/orchestrator_/t/<FOLDER_KEY>/<PACKAGE_ID>";
+
+async function callFn<T>(path: string, input?: unknown, token?: string): Promise<T> {
+  const res = await fetch(`${FN_BASE}${path}`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      ...(token ? { Authorization: `Bearer ${token}` } : {}),
+    },
+    // Never an empty body: the deployed gateway rejects it with 400 errorCode 4804.
+    body: JSON.stringify(input ?? {}),
+  });
+  const body = await res.json();
+  if (!res.ok) throw new Error(body.error ?? `HTTP ${res.status}`);
+  return body as T;
+}
+```
+
+- Always the `api.<HOST>` subdomain — the portal domain sends no CORS headers ([http-semantics-guide.md](http-semantics-guide.md#cors)). curl doesn't enforce CORS, so a portal-domain URL "working" in a terminal proves nothing about the browser.
+- `<ORG_ID>`/`<TENANT_ID>` as GUIDs (preferred over slugs in browser URLs). `<FOLDER_KEY>` is the folder's Key GUID, shared by every function in the folder — discovery recipe in [deployment-guide.md](deployment-guide.md).
+
+## Timeout Budget
+
+The gateway's 25 s timeout / `303 See Other` mechanism → [http-semantics-guide.md](http-semantics-guide.md): a browser caller loses the result permanently; server-side callers aren't CORS-blocked, but recovery via the redirect is undocumented. Budget every browser-invoked function to finish under 20 s ([SKILL.md](../../SKILL.md) JS Rule 6). Enforce it in the handler:
+
+```ts
+handler: async (input, ctx) => Promise.race([
+  actualHandler(input, ctx),
+  new Promise<never>((_, reject) =>
+    AbortSignal.timeout(18_000).addEventListener("abort", () =>
+      reject(new FunctionError("Function timed out", 504)),
+    ),
+  ),
+])
+```
+
+Put `signal: AbortSignal.timeout(8_000)` on every external `fetch` inside the handler so one slow upstream cannot eat the whole budget. Work that cannot fit under 20 s does not belong behind a browser call: move it to a job-mode function ([job-mode-guide.md](job-mode-guide.md)).
+
+## Error Contract for the Frontend
+
+Every non-2xx response from the function runtime has the shape `{ "error": "<MESSAGE>", "details"?: ... }`; gateway errors (last row) carry `{ "errorCode": <N>, "message": "..." }` instead:
+
+| Source | Status / body | Frontend treatment |
+|---|---|---|
+| Thrown `FunctionError(message, status)` | That status, `error` = message | 4xx: user-actionable — surface `error` |
+| Input schema validation failure | `400`, `error` = `"ValidationFailed"`, `details` = per-field errors | Client bug — fix the request shape |
+| Plain `throw` in the handler | `500`, `error` = message, `details` = stack | Generic failure UI; treat as transient |
+| 18 s guard above | `504`, `error` = `"Function timed out"` | Retryable |
+| Gateway (no function reached) | e.g. `403` missing `OR.Default`, `404` errorCode `1623` bad route/folder key, `400` errorCode `4804` empty body | Wiring bug — recheck scope, URL, body |
+
+Branch on status class: 4xx is user-actionable (show `error`, let the user correct input or permissions), 5xx is transient/retryable. Full status semantics → [http-semantics-guide.md](http-semantics-guide.md).
+
+Response shape discipline: the output schema describes success data only, and errors are thrown — a function never returns an `errors[]` array inside a 200. The frontend can therefore branch on `res.ok` alone: ok → body matches the declared output contract; not ok → body carries `{error, details?}`.

package/skills/uipath-functions/references/js/deployment-guide.md

@@ -0,0 +1,109 @@
+# Deployment Guide
+
+Pack → publish → release update → live HTTP endpoint. Covers package anatomy, the production cold-start model (the top source of deployed-only failures), publish credentials, invoke URL discovery, Studio Web push, and solution registration.
+
+## Pack
+
+```bash
+uip function pack            # -> .uipath/<PACKAGE>.<VERSION>.nupkg
+uip function pack --nolock   # exclude package-lock.json from the package
+```
+
+`<PACKAGE>`/`<VERSION>` come from `package.json` `name`/`version`. The package ships **raw sources — no bundling, no compilation**:
+
+- Entire project tree copied verbatim into `content/`, excluding `node_modules`, `.git`, `.env`, `.deno`, `dist`, `.uipath`, `*.nupkg` (extra excludes via `uipath.json` `packOptions.directoriesExcluded`/`filesExcluded`).
+- `package-lock.json` included by default; `--nolock` or `packOptions.includeLockFile: false` drops it.
+- `.npmrc` ships **sanitized**: `@uipath:*` scope lines and credential lines (`_authToken`, `_auth`, `_password`) are stripped; the file is omitted entirely if only comments remain. Custom scope routes (e.g. `@acme:registry=...`) survive.
+- Generated manifests: `entry-points.json`, `bindings_v2.json`, `operate.json`, `package-descriptor.json` — see [bindings-guide.md](bindings-guide.md).
+
+Re-packing the same version **overwrites** the existing `.nupkg`; older version files stay in `.uipath/`, and `publish` picks the most recently modified `.nupkg` by mtime. Bump `version` in `package.json` before packing a release, or you may publish a stale file.
+
+## Cold Start — How Production Runs the Package
+
+The production worker does at cold start what pack deliberately did not do: it extracts `content/`, runs `npm install --omit=dev` from the shipped `package-lock.json`, then loads the `.ts` sources directly. **The install runs with no credentials** — pack stripped tokens from `.npmrc`, and no GitHub or private-registry token is available at install time. Everything below follows from that:
+
+1. **Every runtime dependency must be public npm and listed in `dependencies`.** `--omit=dev` skips `devDependencies` entirely. The SDK (`@uipath/coded-functions-js-sdk`) stays in `devDependencies` — the platform provides the runtime.
+2. **A runtime dep the lockfile resolves to a private registry breaks the install** — the function crashes or hangs with no logs. Routing `@uipath` to GitHub Packages in the project `.npmrc` is safe for pack-time tooling (that line is stripped from the shipped copy), but every `dependencies` entry in `package-lock.json` must show a `resolved` URL on `registry.npmjs.org`. Gate before packing — after adding a dependency, or whenever `.npmrc` carries custom registry routes: `grep '"resolved"' package-lock.json | grep -v registry.npmjs.org` must print nothing.
+3. **Regenerate the lockfile after any `package.json` change** — run `npm install`, then pack. A stale lockfile fails the production install: `errorCode 4801` on every route.
+4. **Extensionless intra-project imports hang cold start silently** — local dev resolves them, production does not ([SKILL.md](../../SKILL.md) JS Rule 4).
+5. **Genuinely private code cannot be installed — vendor it as source.** Copy it into the project (`functions/_helpers.ts`, or any non-excluded directory such as `lib/`) and import it with explicit `.ts` extensions.
+
+Failure mode when any of these is violated (known sharp edge — install failures have no error surface yet): all functions in the package hang for up to 15 minutes with no logs — exception: a stale lockfile (item 3) surfaces as `errorCode 4801` instead. A healthy deploy may also 500 once on the first call while cold start runs — retry before diagnosing.
+
+## Publish
+
+```bash
+uip function publish --feed-id <FEED_ID>   # omit --feed-id for the interactive feed picker
+```
+
+Uploads the newest `.nupkg` (by mtime) from `.uipath/` to an Orchestrator process feed. Credentials via flags or env vars:
+
+| Flag | Env var | Value |
+|---|---|---|
+| `--url` | `UIPATH_URL` | platform base URL |
+| `--org` | `UIPATH_ORGANIZATION_NAME` | organization **name** |
+| `--tenant` | `UIPATH_TENANT_NAME` | tenant **name** |
+| `--token` | `UIPATH_ACCESS_TOKEN` | access token |
+
+> Names, not GUIDs — distinct from the handler-local `UIPATH_ORG_ID`/`UIPATH_TENANT_ID` fallbacks ([local-dev-guide.md](local-dev-guide.md)).
+
+Publish failures: `401`/`403` → re-check the credential env vars above; feed errors → rerun without `--feed-id` for the interactive picker.
+
+### Manual step: update the Function Release
+
+Publishing uploads the version, but the Function Release stays pinned to the previous one until you update it in Orchestrator → **Automations → Processes** (REST: `/odata/Releases` — the UI says "Processes", the API says "Releases"). Only then does Orchestrator re-read the manifests and sync triggers — full lifecycle table (rename = trigger delete+create) → [bindings-guide.md](bindings-guide.md).
+
+## Invoke
+
+```text
+https://api.<HOST>/<ORG_ID>/<TENANT_ID>/orchestrator_/t/<FOLDER_KEY>/<PACKAGE_ID>/<SLUG>
+```
+
+| Segment | Value |
+|---|---|
+| `api.<HOST>` | the `api.*` subdomain (e.g. `api.uipath.com`) — browsers must call `api.*` ([http-semantics-guide.md](http-semantics-guide.md#cors)) |
+| `<ORG_ID>` / `<TENANT_ID>` | org/tenant **GUIDs** for browser callers (slugs also work from curl) |
+| `<FOLDER_KEY>` | the **folder's Key GUID** — same for every function in the folder, not per-trigger |
+| `<PACKAGE_ID>` | `package.json` `name` (sanitized) |
+| `<SLUG>` | `defineFunction` `path` without the leading `/` — its own segment after `<PACKAGE_ID>` |
+
+```bash
+curl -s -X POST "https://api.<HOST>/<ORG_ID>/<TENANT_ID>/orchestrator_/t/<FOLDER_KEY>/<PACKAGE_ID>/<SLUG>" \
+  -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" -d '{}'
+```
+
+Always send `Content-Type: application/json` and a JSON body — `'{}'` when the function takes no input ([SKILL.md](../../SKILL.md) JS Rule 7). GET functions take input as query-string parameters instead.
+
+### Discovering `<FOLDER_KEY>` and slugs
+
+```bash
+curl -s "https://api.<HOST>/<ORG_ID>/<TENANT_ID>/orchestrator_/odata/HttpTriggers" \
+  -H "Authorization: Bearer <TOKEN>" -H "X-UIPATH-OrganizationUnitId: <FOLDER_ID>"
+```
+
+Each row carries `Method`, `Slug`, `Release.Name` (= `<PACKAGE_ID>`), and `ExternalReference` of the form `<METHOD> <PACKAGE_ID>/<SLUG> <FOLDER_KEY>` — the trailing GUID is the `<FOLDER_KEY>` for the URL.
+
+| Wrong move | Result |
+|---|---|
+| Trigger's own `Id` as `<FOLDER_KEY>` | `404 errorCode 1623` ("HTTP trigger not found") |
+| Wrong folder key or unmatched slug | `404 errorCode 1623` |
+| `odata/ApiTriggers` with `$filter=ProcessKey ...&$select=Key,Name,Url` | `400 errorCode 1000` — the DTO lacks those fields; use `HttpTriggers` |
+
+Deployed status codes and the 25 s timeout / 303 behavior → [http-semantics-guide.md](http-semantics-guide.md); calling from a Coded App frontend → [coded-app-wiring-guide.md](coded-app-wiring-guide.md).
+
+## Studio Web push
+
+```bash
+uip function push --project-id <PROJECT_ID>
+```
+
+Diff-by-hash source sync into a Studio Web project (same credential env vars as publish). Updates `.uipath/studio_metadata.json` (project version auto-increments; open editors prompt Reload); never touches `project.uiproj`, `.project`, or `.settings`.
+
+## Solution registration
+
+JS/TS projects have no `uip function init` (Python-only) and need none — the `uipath.json` marker already identifies the project:
+
+```bash
+uip solution projects add <FUNCTION_PROJECT_PATH>
+uip solution pack   # packs the function project in-process; no separate uip function pack needed
+```

package/skills/uipath-functions/references/js/http-semantics-guide.md

@@ -0,0 +1,80 @@
+# HTTP Semantics Guide
+
+The HTTP contract of a coded function — how requests become `input`, how routes match, how returns and throws become responses — both under local `uip function serve` and deployed behind the Orchestrator gateway. Handler authoring → [authoring-guide.md](authoring-guide.md); invoke URL construction → [deployment-guide.md](deployment-guide.md).
+
+## Input assembly
+
+| Source | Rule |
+|---|---|
+| GET | query-string entries become `input`; body never read |
+| POST/PUT/PATCH/DELETE | JSON body becomes `input`; locally an empty or unparseable body becomes `{}` (deployed, empty body is rejected by the gateway first — see table below) |
+| Path params | merged UNDER input (`{...params, ...rawInput}`) — a body/query key shadows a same-named path param; params stay available uncoerced on `ctx.params` |
+
+Query params are independent of path matching and validate through the `input` schema. Use path params for identity, query params for optional filters.
+
+## Validation pipeline
+
+Runs in the runtime (ajv compiled there — never a project dependency), in order:
+
+1. Input is validated against the `input` schema before the handler runs; failure returns `400` with body `{"error":"ValidationFailed","details":{"formErrors":[...],"fieldErrors":{...}}}` and the handler is never called.
+2. GET query values arrive as strings; coercion to schema types (number/boolean) is automatic for schema-first contracts. Only zod contracts need `z.coerce.number()` — the runtime never replaces a Standard Schema validator with the derived JSON Schema (that would drop refinements and coercion).
+3. `@default` values (JSDoc tag on optional props, or schema `default`) are filled into missing fields before the handler sees `input`.
+4. Output is validated against the `output` schema after the handler returns; failure returns `500` with body `{"error":"Handler returned invalid output","details":{...}}`.
+
+## Route matching
+
+The deployed trigger slug is `path` minus the leading `/`, pattern segments preserved verbatim (the `bindings_v2.json` metadata field `Slug` stores `path` verbatim, leading `/` included — [bindings-guide.md](bindings-guide.md)); resolution is route matching, not string comparison. Local serve and deployed agree.
+
+| Pattern | Matches |
+|---|---|
+| `:param` | exactly one segment → `ctx.params.<NAME>` (string) |
+| `:param{regex}` | one segment, regex-constrained |
+| `:param?` | that segment or nothing |
+| trailing `*` | one or more trailing segments; catch-all only — NOT captured as a param |
+
+Rules:
+
+- Routes are sorted by specificity, mirroring Orchestrator's `HttpTriggerMatcher.CompareSpecificity`: a literal segment beats a param regardless of declaration order — `/users/me` wins over `/users/:id`.
+- Extra segments are not absorbed: `/list/:filter?` does not match `/list/a/b`. Add an explicit `*` route for a catch-all.
+- A deployed request that matches no trigger returns:
+
+```json
+{ "message": "HTTP trigger not found for path 'my-functions/invoices/a/b'.", "errorCode": 1623 }
+```
+
+  as a `404`. The same 1623 appears when the invoke URL carries a wrong folder key — see [deployment-guide.md](deployment-guide.md).
+
+## Response mapping
+
+| Handler outcome | HTTP result |
+|---|---|
+| plain value / void | `200`, value JSON-serialized (void → body `null`) |
+| `FunctionResponse {status, body?, headers?}` (incl. helpers `ok`/`created`/`noContent`/`badRequest`/...) | status passthrough; `204` or undefined body → empty body |
+| raw `Response` | passed through untouched |
+| thrown `FunctionError(message, status)` | that status (default `500`), body `{"error": <MESSAGE>, "details"?: ...}` |
+| any other throw | `500`, body `{"error": <MESSAGE>, "details": <STACK>}` |
+
+- A `FunctionError`'s `errorCode` never appears in an HTTP response body — it maps only onto the job fault surface ([job-mode-guide.md](job-mode-guide.md)). `errorCode` values that DO show up in HTTP bodies (1623, 4804, 4801) come from the gateway, not from your function.
+- The plain-throw `500` carries the real message and stack trace unsanitized — the code is customer-owned, so this holds locally and deployed. Still throw `FunctionError` for anything a caller should read (see [SKILL.md](../../SKILL.md) JS Rule 1; details in [authoring-guide.md](authoring-guide.md#errors)).
+
+## CORS
+
+- **Local serve:** `origin: '*'`; `allowHeaders` covers `Content-Type`, `Authorization`, and the full `X-UiPath-*` platform-header set. Any local frontend (e.g. a coded app on :5173) fetches `http://localhost:7070/<PATH>` directly — no proxy.
+- **Deployed:** only the `api.<HOST>` subdomain serves CORS headers; the portal domain does not. Browsers MUST call `https://api.<HOST>/...`; `curl` and server-side code can use either domain. URL shape → [deployment-guide.md](deployment-guide.md); browser wiring → [coded-app-wiring-guide.md](coded-app-wiring-guide.md).
+
+## Deployed gateway behaviors
+
+Sharp edges of the current PublicPreview gateway — observed behavior, not guarantees. None reproduce under local serve, so test deployed too ([local-dev-guide.md](local-dev-guide.md) covers the local loop).
+
+| Symptom | Cause | Handling |
+|---|---|---|
+| `303 See Other` after 25 s | gateway timeout; redirect target is a portal-domain polling URL WITHOUT CORS | browser callers lose the result permanently — keep the handler under 20 s: `AbortSignal.timeout(...)` on every external call plus an overall guard (`Promise.race` at ~18 s). Server-side callers aren't CORS-blocked from the 303 target, but recovering the result that way is undocumented — apply the same budget everywhere |
+| `400 errorCode 4804` | empty POST body (deployed only) | always send `body: '{}'` |
+| `403` | caller token missing `OR.Default` scope | fix the token's scopes → [coded-app-wiring-guide.md](coded-app-wiring-guide.md) |
+| `404 errorCode 1623` | no trigger matched: wrong slug, wrong folder key, or pattern mismatch | see Route matching + [deployment-guide.md](deployment-guide.md) |
+| single `500` right after deploy | cold start | retry once |
+| `errorCode 4801` on every route | stale `package-lock.json` in the package | regenerate lockfile, re-pack → [deployment-guide.md](deployment-guide.md) |
+
+## Path naming
+
+The slug is public API surface: it appears in every caller's invoke URL, and renaming `path` is a trigger delete+create — every existing caller breaks ([bindings-guide.md](bindings-guide.md)). Choose short noun slugs and let the method carry the verb: `POST /invoice`, not `POST /create-invoice`; `GET /invoices/:id`, not `GET /get-invoice`.