> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Procedure SDK for Node

> Current @gloo/procedure-sdk-node exports and procedure-sandbox usage.

`@gloo/procedure-sdk-node` is preinstalled in a Forge Node procedure sandbox. It reads the injected
`GLOO_PROCEDURE_SESSION` and `GLOO_PROXY_URL`; authors do not provide vendor credentials.

## Root exports

| Area | Exports |
| - | - |
| Capabilities | `invokeCapability`, `InvokeCapabilityResponse` |
| Files | `putFile`, `getFile` and their argument/result types |
| Composition | `runProcedure`, `RunProcedureArgs`, `RunProcedureResult` |
| Progress | `emitProgress`, `ProgressEvent` |
| Session | `readSession`, `ProcedureSession`, `ProcedureSessionError` |
| Errors | `ProcedureApiError`, `ProcedureProxyOperation`, `toProcedureErrorEnvelope`, `ProcedureErrorEnvelope` |
| Manifest contract | `PROCEDURE_ERROR_CODES` and shared manifest/runtime types |

The package root is the public import surface. Do not deep-import implementation files.

## Call a capability

The current function takes positional `domain`, `operation`, and `args` values:

```ts theme={null}
import { invokeCapability } from "@gloo/procedure-sdk-node";

const result = await invokeCapability<{ status: number; body: unknown }>(
  "network",
  "fetch",
  { url: "https://example.com/", method: "GET", timeoutMs: 10_000 },
);
console.log(result.providerId, result.data.status, result.data.body);
```

The manifest must declare `network`, and dispatch must grant the session that domain and the `fetch` operation. Use an approved URL for the procedure's task. The platform proxy resolves the network provider and records the call. Its normalized response has `status`, `headers`, and `body`; JSON content is decoded and other content is returned as text. The capability performs one request without retrying it. Vendor secrets must not be embedded in these arguments.

For direct Linear pagination, use the [Vendor Connection procedure](https://docs.gloo.com/forge/build/built-in-procedures.md#linear-paginate-issues), not an invented `linear` capability domain.

## Write and read files

```ts theme={null}
import { getFile, putFile } from "@gloo/procedure-sdk-node";

const { fileId } = await putFile({
  source: {
    kind: "inline",
    contentType: "text/markdown",
    filename: "report.md",
    text: report,
  },
  bind: { kind: "workflow_output", outputName: "report" },
});

const source = await getFile(inputFileId, "text");
console.log(source.mimeType, source.content);
```

`getFile` modes are `text`, `bytes`, and `stream`. `putFile` inline sources carry exactly one of
`text` or `bytes`; render sources name a renderer and args. Bindings include workflow output, run
scratch, worker scope, and chat attachment where the invocation permits them.

## Compose and report progress

`runProcedure(args)` invokes a registered procedure through the same session. Prefer a workflow
edge when the composition should be visible to operators. `emitProgress(event)` validates and emits
best-effort progress; it is synchronous and does not return a promise.

## Session and errors

`readSession()` parses the injected signed session and throws `ProcedureSessionError` when it is
missing or malformed. `ProcedureApiError` represents proxy and contract failures.
`toProcedureErrorEnvelope(error)` converts an unknown exception into the bounded error shape a
procedure can return or log safely.

Handle `ProcedureApiError.code` using the exported `PROCEDURE_ERROR_CODES`; do not branch on message
text or invent new codes. Some codes are produced by the platform before or after the sandbox and
cannot be raised by author code.

See [Author a procedure](https://docs.gloo.com/forge/build/author-a-procedure.md) and [Python SDK](https://docs.gloo.com/forge/reference/procedure-sdk-python.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.