Skip to main content

TypeScript SDK

Use @glixo/extension-sdk for typed guest envelopes, broker adapters, scoped state, workspace access and bounded NDJSON streams. Your entry point imports generated WIT functions and exports a guest or provider object. It runs inside the WebAssembly component, rather than as an ordinary Node.js service.

Set up and build

Create the Text Stats project using the SDK overview command. Its CLI scaffold includes vendor/glixo-extension-sdk, WIT files and compiler locks. Run from the generated project:

npm ci --prefix vendor/glixo-extension-sdk --ignore-scripts
npm run build --prefix vendor/glixo-extension-sdk
npm ci --install-links
npm run build
npm test

The recipe uses Node.js 22.14.0, npm 10.9.2, TypeScript 6.0.3, esbuild 0.28.2, Jco 1.35.0, componentize-js 0.23.0 and preview2-shim 0.25.0. It typechecks your code, bundles it while leaving glixo:* imports external, and componentizes it using wit/. The result is dist/glixo-extension.component.wasm. See the public project scripts.

For a separate library consumer, install the published SDK:

npm install --save-exact @glixo/extension-sdk@0.1.0

In a scaffold, the file:vendor/glixo-extension-sdk dependency already provides the SDK. Keep it for a reproducible template build, or intentionally replace that dependency with the published package and update the lockfile. Do not install both routes. The published CLI 0.3.5 cannot reliably run its TypeScript build recipe; use the project scripts above as described in Build and package.

Package exports

All of these are available from the root import or their subpath:

Import Exports and purpose
@glixo/extension-sdk/http Result<T>, Header, BrokerRequest, Broker, NdjsonStream, DEFAULT_READ_BYTES, DEFAULT_MAX_LINE_BYTES
@glixo/extension-sdk/state ScopedState: get, set, list and delete
@glixo/extension-sdk/workspace WorkspaceReader: search and read using a host handle
@glixo/extension-sdk/logging ExtensionLogger: structured level and message arguments
@glixo/extension-sdk/guest GuestEnvelope<TConfiguration,TInput>, GuestContext, EndpointGrant, GuestReply<TResponse>
@glixo/extension-sdk/llm ToolCallDetails, Usage, FinishReason, ContentPart, ProviderEvent
@glixo/extension-sdk/wit captureWitResult, witErrorText, throwWitError

See the export source. The guest, state, workspace, logging and LLM interfaces are types, not implementations that open a connection or enforce consent. Supply the generated host functions through adapters; see host APIs and HTTP adapters.

Export a guest function

In the Text Stats scaffold, src/handler.ts implements handleWorkflowTextStats. Keep that handler and replace src/guest.ts with this entry point:

import { throwWitError } from '@glixo/extension-sdk/wit';
import { handleWorkflowTextStats } from './handler.js';

export const guest = {
  invoke(requestJson: string): string {
    try {
      return JSON.stringify(handleWorkflowTextStats(requestJson));
    } catch (error) {
      throwWitError(error);
    }
  },
};

The host passes the complete envelope as JSON. The handler checks kind, contributionId and each input field before computing the result. Returning JSON that matches the contribution's outputSchema is part of your API. Read the complete handler and invocation format.

Handle WIT results and options

Jco returns the success value of an imported result<T,string> directly; it throws the string on failure. An option<T> is T | undefined. A variant uses its WIT tag, such as { tag: 'tool-call-details', val: details }.

captureWitResult converts an imported function's behavior to the SDK's Result<T> union:

import { captureWitResult, witErrorText } from '@glixo/extension-sdk/wit';

export function tryRead<T>(read: () => T): T | undefined {
  const result = captureWitResult(read);
  if (!result.ok) throw new Error(result.error);
  return result.value;
}

export function publicError(error: unknown): string {
  return witErrorText(error);
}

witErrorText limits errors to 256 characters and uses guest_error for an empty or unrecognized value. At an exported WIT result boundary, use throwWitError: it throws a primitive string for the error arm. Throwing an Error object at that boundary produces a component trap. Internal functions can use Error normally; the exported wrapper converts it. See WIT helpers.

Test, package and run

Test handlers with ordinary Node tests and injected adapters. Include malformed JSON, wrong contribution IDs, permission-denied adapter responses, oversized values, and HTTP chunks split across UTF-8 or newline boundaries. An SDK type assertion does not validate JSON at runtime.

After the build and handler tests, run glxdev pack and glxdev verify --output ./dist/package. Follow signing and installation to activate the extension in Glixo. A plain Node process cannot resolve glixo:* imports; execute the component through Glixo for actual host operations. The panel's browser entry point is a separate artifact with a separate UI bridge.