@alga-psa/extension-runtime

Utility types and helper functions for Alga extension components compiled with componentize-js.

Installation

``bash
npm install @alga-psa/extension-runtime
`

Usage

`ts
import { Handler, jsonResponse } from '@alga-psa/extension-runtime';

export const handler: Handler = async (request, host) => {
const secret = await host.secrets.get('alga_api_key');
await host.logging.info(Handling request for ${request.context.tenantId});
return jsonResponse({ ok: true, secret, path: request.http.path });
};
`

The helpers mirror the WIT definitions in ee/runner/wit/extension-runner.wit.

Host Bindings

The HostBindings interface provides access to host capabilities:

$3


`typescript
host.context.get(): Promise
`
Get execution context (tenant, extension, request IDs).

$3

`typescript
host.secrets.get(key: string): Promise
host.secrets.list(): Promise
`
Access install-scoped secrets. Requires cap:secrets.get.

$3

`typescript
host.http.fetch(request: HttpRequest): Promise
`
Make outbound HTTP requests. Requires cap:http.fetch.

$3

`typescript
host.storage.get(namespace: string, key: string): Promise
host.storage.put(entry: StorageEntry): Promise
host.storage.delete(namespace: string, key: string): Promise
host.storage.list(namespace: string): Promise
`
Key-value storage. Requires cap:storage.kv.

$3

`typescript
host.logging.info(message: string): Promise
host.logging.warn(message: string): Promise
host.logging.error(message: string): Promise
`
Emit structured logs. Requires cap:log.emit.

$3

`typescript
host.uiProxy.callRoute(route: string, payload?: Uint8Array): Promise
`
Call host-mediated proxy routes for UI flows. Requires cap:ui.proxy.

$3

`typescript
host.user.getUser(): Promise
`
Get current user information. Requires cap:user.read (granted by default).

`typescript
interface UserData {
tenantId: string;
clientName: string;
userId: string;
userEmail: string;
userName: string;
userType: string; // "internal" or "client"
}
`

$3


`typescript
host.scheduler.list(): Promise
host.scheduler.get(scheduleId: string): Promise
host.scheduler.create(input: CreateScheduleInput): Promise
host.scheduler.update(scheduleId: string, input: UpdateScheduleInput): Promise
host.scheduler.delete(scheduleId: string): Promise
host.scheduler.getEndpoints(): Promise
`
Manage scheduled tasks. Requires cap:scheduler.manage.

Helper Functions

$3

`typescript
jsonResponse(body: unknown, init?: Partial): ExecuteResponse
`
Create a JSON response with proper headers.

$3

`typescript
emptyResponse(status?: number): ExecuteResponse
`
Create an empty response (default status 204).

$3

`typescript
createMockHostBindings(overrides?: Partial): HostBindings
`
Create mock host bindings for testing.

Using WIT Imports

When building with jco componentize, host capabilities are imported from WIT modules. Create a wrapper index.ts:

`typescript
// Import WIT functions
// @ts-ignore
import { getUser } from 'alga:extension/user';
// @ts-ignore
import { logInfo } from 'alga:extension/logging';

// Build HostBindings
const host: HostBindings = {
user: { getUser: async () => getUser() },
logging: { info: async (msg) => logInfo(msg), / ... / },
// ... other bindings
};

export async function handler(request: ExecuteRequest): Promise {
return myHandler(request, host);
}
`

See User Host API Guide for complete examples.

Building

Run npm run build` before publishing.