The ctx object

Every Helix function execution receives a ctx object as its handler argument. It carries the project-scoped key-value store, outbound HTTP including authenticated calls, AI model calls, logging, the validated request input, response helpers, execution metadata, and caller identity. Shared code outside the handler can reach the same object with getContext().

Surface

kv() takes no argument and is always project-scoped. identity ships, but only user.id populates reliably right now, so treat email, name, groups, roles, and org as incomplete. HTTP requests and cron schedules (defineSchedule) are the triggers a function can have. The shipped data service is the project-scoped key-value store.

Execution metadata

Five fields identify where an execution runs and who invoked it. Each is null when unknown, for example in an unprovisioned local project.

projectId, workspaceId, and organizationId identify the deployment; userId identifies the caller. See ctx.identity.

getContext()

Handlers receive ctx as a parameter. Shared utilities deeper in the call chain can access the same context without threading it through every call:

import { getContext } from '@trayai/helix-sdk';

function getContext(): FunctionContext

The context is stored in Node.js AsyncLocalStorage, scoped per execution, so concurrent requests never bleed into each other. Calling getContext() outside a function execution throws: “getContext() called outside of a Helix function execution.”

// functions/_shared/salesforce.ts
import { getContext } from '@trayai/helix-sdk';

const AUTH = 'salesforce_prod';
const API = 'https://acme.my.salesforce.com/services/data/v59.0';

export async function query<T = any>(soql: string): Promise<T[]> {
  const { http } = getContext(); // no ctx parameter needed
  const result = await http
    .authed(AUTH)
    .get(`${API}/query`, { searchParams: { q: soql } })
    .json<{ records: T[] }>();
  return result.records;
}

runWithContext() for tests

To unit test shared code that calls getContext(), wrap the call in a mock context:

// tests/shared/salesforce.test.ts
import { runWithContext } from '@trayai/helix-sdk/testing';
import { query } from '../functions/_shared/salesforce';

test('query returns contacts', async () => {
  const result = await runWithContext(
    { http: mockKyInstance, kv: mockKvStore },
    () => query('SELECT Id FROM Contact'),
  );

  expect(result).toEqual([{ Id: '003xx...' }]);
});

Availability by function type

Not every field exists on every function type. Accessing an unavailable field throws a clear runtime error naming the function types that support it.

For how each function type is declared and routed, see the functions and routing guide.