@prxy/module-sdk

Public TypeScript SDK for building prxy.monster gateway modules.

A module is composable middleware for an LLM API pipeline. It can pre-process requests, post-process responses, observe streaming chunks, or short-circuit the pipeline (e.g. on a cache hit). The same module runs in both the cloud edition and the self-hosted local edition — the SDK abstracts storage so you write the logic once.

Think VS Code extensions, but for LLM API middleware.

Install

npm install @prxy/module-sdk
# or
pnpm add @prxy/module-sdk
# or
yarn add @prxy/module-sdk

The SDK is the contract only — no runtime dependencies on the gateway. Declare it as a peerDependency so the gateway can hoist a single copy:

{
  "peerDependencies": {
    "@prxy/module-sdk": "^1.0.0"
  }
}

Hello world

import type { Module } from '@prxy/module-sdk';

const helloLogger: Module = {
  name: 'hello-logger',
  version: '1.0.0',

  async pre(ctx) {
    ctx.logger.info('saw request', {
      model: ctx.request.model,
      messages: ctx.request.messages.length,
    });
    return { continue: true };
  },

  async post(ctx) {
    ctx.logger.info('done', { durationMs: ctx.durationMs });
  },
};

export default helloLogger;

Compile to ESM (tsc) and load via PRXY_PIPE:

PRXY_PIPE='exact-cache,patterns,/path/to/dist/hello-logger.js'

Lifecycle

| Hook | When it runs | Can short-circuit? | Blocks the response? | |---|---|---|---| | init(storage) | Once at gateway boot | n/a | n/a | | pre(ctx) | Before the upstream call | Yes — return { continue: false, response } | Yes | | stream(chunk, ctx) | Per SSE chunk on streaming responses | No (transform-only) | Per chunk | | post(ctx) | After the response is delivered | No | No (fire-and-forget) |

Errors in pre are logged and treated as { continue: true }. Errors in post are swallowed. The pipeline is a "best-effort middleware chain" — one broken module never denies a user a response.

Storage

Modules access storage through the StorageAdapter interface, which the gateway provides via ctx.storage:

async pre(ctx) {
  // KV (Redis / in-memory / Upstash, depending on edition)
  await ctx.storage.kv.set('hello', 'world', 60);

  // Database (Postgres + pgvector cloud, SQLite + sqlite-vec local)
  const { data } = await ctx.storage.db
    .from('my_table')
    .select('*')
    .eq('user_id', ctx.apiKey.user_id)
    .limit(10);

  // Blob (R2 / GCS / local filesystem)
  await ctx.storage.blob.put('archives/foo.json', JSON.stringify({}));

  return { continue: true };
}

The same code runs in cloud and local mode — pick the abstraction, not the backend.

Publishing your module to the marketplace

1. Build a module against this SDK.
2. Publish to npm under your own scope (@your-name/your-module).
3. Open a PR to the public registry with a manifest.
4. CI validates the manifest. A maintainer reviews and merges.
5. Your module appears at https://modules.prxy.monster.

Full publishing guide: https://docs.prxy.monster/sdk/publishing

Documentation

• Interface reference: https://docs.prxy.monster/sdk/interface
• Lifecycle: https://docs.prxy.monster/sdk/lifecycle
• Storage: https://docs.prxy.monster/sdk/storage-access
• Publishing: https://docs.prxy.monster/sdk/publishing
• Marketplace: https://docs.prxy.monster/sdk/marketplace

Examples

The 12 official modules shipped by prxy.monster all use this SDK. See packages/modules-core for full source — ipc, mcp-optimizer, semantic-cache, exact-cache, patterns, cost-guard, router, prompt-optimizer, tool-cache, guardrails, rehydrator, compaction-bridge.

License

MIT © ekkOS Technologies Inc.