Module interface

pnpm add @prxy/module-sdk @prxy/shared-types

import type { Module } from '@prxy/module-sdk';
 
export const hello: Module = {
  name: 'hello',
  version: '1.0.0',
 
  async pre(ctx) {
    ctx.logger.info('hello from a module');
    return { continue: true };
  },
};

export interface Module {
  /** Stable module name. Must match the string used in PRXY_PIPE entries. */
  name: string;
 
  /** Semver. Surfaced in /v1/pipeline responses for debugging. */
  version: string;
 
  /** Optional: one-shot setup at gateway start. Runs once per process. */
  init?(storage: StorageAdapter): Promise<void>;
 
  /** Optional: pre-request hook. Can mutate the request or short-circuit. */
  pre?(ctx: RequestContext): Promise<PreResult>;
 
  /** Optional: per-chunk hook for streaming responses. */
  stream?(chunk: CanonicalChunk, ctx: ResponseContext): Promise<CanonicalChunk>;
 
  /** Optional: post-response hook. Side effects only. */
  post?(ctx: ResponseContext): Promise<void>;
}

export interface RequestContext {
  request: CanonicalRequest;       // mutable — change anything
  metadata: Map<string, unknown>;  // shared across modules
  storage: StorageAdapter;         // KV / DB / blob
  apiKey: ApiKeyInfo;              // { id, userId, tier, ... }
  logger: Logger;                  // pino-style
  startTime: number;               // ms timestamp
}

export interface ResponseContext extends RequestContext {
  response: CanonicalResponse;
  durationMs: number;
}

export type PreResult =
  | { continue: true }
  | { continue: false; response: CanonicalResponse };

import type { Module } from '@prxy/module-sdk';
 
export function requestCounter(): Module {
  return {
    name: 'request-counter',
    version: '1.0.0',
 
    async init(storage) {
      // initialize the count if it doesn't exist
      const existing = await storage.kv.get('counter:total');
      if (!existing) await storage.kv.set('counter:total', '0');
    },
 
    async pre(ctx) {
      const total = await ctx.storage.kv.get('counter:total');
      ctx.metadata.set('request_number', Number.parseInt(total ?? '0', 10) + 1);
      return { continue: true };
    },
 
    async post(ctx) {
      // increment in the post hook so failed pre-hooks don't inflate the count
      const total = await ctx.storage.kv.get('counter:total');
      const n = Number.parseInt(total ?? '0', 10) + 1;
      await ctx.storage.kv.set('counter:total', n.toString());
      ctx.logger.info({ total: n }, 'request counted');
    },
  };
}

import type { Module } from '@prxy/module-sdk';
import { calculateActualCost, estimateRequestCost } from './lib/cost.js';
import { errorResponse } from './lib/errors.js';
 
export interface CostGuardConfig {
  perRequest?: number;
  perDay?: number;
  perMonth?: number;
}
 
export function costGuard(config: CostGuardConfig = {}): Module {
  return {
    name: 'cost-guard',
    version: '1.0.0',
 
    async pre(ctx) {
      const estimated = estimateRequestCost(ctx.request);
      ctx.metadata.set('cost.estimated', estimated);
 
      if (config.perRequest != null && estimated > config.perRequest) {
        return {
          continue: false,
          response: errorResponse('cost_limit_per_request', 'Request exceeds cap', {
            limit: config.perRequest, estimated, status: 429,
          }),
        };
      }
      // ...per-day, per-month checks omitted...
      return { continue: true };
    },
 
    async post(ctx) {
      if (ctx.response.stopReason === 'error') return;
      const actual = calculateActualCost(ctx.request, ctx.response);
      ctx.metadata.set('cost.actual', actual);
      // ...write spend counters to KV...
    },
  };
}