@palveron/sdk 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,225 @@
+type Decision = 'ALLOWED' | 'BLOCKED' | 'MODIFIED' | 'ERROR';
+type RiskLevel = 'minimal' | 'limited' | 'high' | 'unacceptable';
+type Sensitivity = 'low' | 'medium' | 'high';
+interface PalveronConfig {
+    /** API key (starts with pv_live_ or pv_test_) */
+    apiKey: string;
+    /** Gateway base URL (default: https://gateway.palveron.com) */
+    baseUrl?: string;
+    /** Request timeout in ms (default: 30000) */
+    timeout?: number;
+    /** Max retry attempts on transient failures (default: 3) */
+    maxRetries?: number;
+    /** Base delay for exponential backoff in ms (default: 500) */
+    retryBaseDelay?: number;
+    /** Custom logger (default: console) */
+    logger?: PalveronLogger;
+    /** Custom headers added to every request */
+    headers?: Record<string, string>;
+    /** Circuit breaker: max consecutive failures before opening (default: 5) */
+    circuitBreakerThreshold?: number;
+    /** Circuit breaker: cooldown in ms before half-open retry (default: 30000) */
+    circuitBreakerCooldown?: number;
+}
+interface PalveronLogger {
+    debug(message: string, meta?: Record<string, unknown>): void;
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+}
+interface Attachment {
+    /** MIME type (e.g. "image/png", "audio/wav", "application/pdf") */
+    contentType: string;
+    /** Base64-encoded data */
+    data: string;
+    /** Optional filename */
+    filename?: string;
+    /** Optional per-attachment metadata (GPS, resolution, etc.) */
+    metadata?: Record<string, unknown>;
+}
+interface RequestContext {
+    /** MCP server URL if applicable */
+    mcpServer?: string;
+    /** MCP tool name */
+    toolName?: string;
+    /** Agent chain depth for recursive calls */
+    chainDepth?: number;
+    /** Source system identifier ("ros2", "unity", "cursor-ide", etc.) */
+    sourceSystem?: string;
+    /** Session ID for conversation tracking */
+    sessionId?: string;
+}
+interface VerifyRequest {
+    /** The prompt or input text to verify */
+    prompt: string;
+    /** Pre-extracted text from attachments (optional, server extracts if absent) */
+    extractedText?: string;
+    /** Arbitrary metadata passed through to the trace */
+    metadata?: Record<string, unknown>;
+    /** Multi-modal attachments (images, audio, documents, code) */
+    attachments?: Attachment[];
+    /** Agentic context (MCP, tool chains, source systems) */
+    context?: RequestContext;
+}
+interface Finding {
+    risk: 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+    category: string;
+    description: string;
+    confidence: number;
+}
+interface VerifyResponse {
+    /** Governance decision */
+    decision: Decision;
+    /** Modified/sanitized output (present when decision is MODIFIED) */
+    output: string;
+    /** Human-readable reason for the decision */
+    reason: string;
+    /** Unique trace ID for audit trail */
+    traceId: string;
+    /** SHA-256 integrity hash of the governance decision */
+    integrityHash: string;
+    /** Whether this trace will be anchored to Flare blockchain */
+    shouldAnchor: boolean;
+    /** Flare blockchain status */
+    flareStatus: string;
+    /** Flare transaction hash (populated after anchoring) */
+    flareTxHash: string | null;
+    /** Detected content type */
+    contentType: string;
+    /** Security findings (secrets, PII, policy violations) */
+    findings: Finding[];
+    /** Server-side latency in milliseconds */
+    latencyMs: number;
+}
+interface PolicyListResponse {
+    policies: Array<{
+        id: string;
+        name: string;
+        prompt: string;
+        environment: string;
+        contentTypes: string[];
+        createdAt: string;
+        updatedAt: string;
+    }>;
+}
+interface HealthResponse {
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    version: string;
+    uptime: number;
+    checks: Record<string, {
+        status: string;
+        latencyMs: number;
+    }>;
+}
+declare class PalveronError extends Error {
+    readonly code: string;
+    readonly statusCode: number;
+    readonly requestId: string | null;
+    readonly retryable: boolean;
+    constructor(message: string, opts: {
+        code: string;
+        statusCode: number;
+        requestId?: string | null;
+        retryable?: boolean;
+    });
+}
+declare class PalveronAuthenticationError extends PalveronError {
+    constructor(message: string, requestId?: string | null);
+}
+declare class PalveronRateLimitError extends PalveronError {
+    readonly retryAfterMs: number;
+    constructor(message: string, retryAfterMs: number, requestId?: string | null);
+}
+declare class PalveronValidationError extends PalveronError {
+    readonly field: string | null;
+    constructor(message: string, field?: string, requestId?: string | null);
+}
+declare class PalveronCircuitOpenError extends PalveronError {
+    constructor();
+}
+declare class PalveronTimeoutError extends PalveronError {
+    constructor(timeoutMs: number, requestId?: string | null);
+}
+declare class Palveron {
+    private readonly config;
+    private readonly circuit;
+    constructor(config: PalveronConfig);
+    /**
+     * Send a governance verification request.
+     * This is the primary method — every LLM call should go through this.
+     *
+     * @example
+     * ```typescript
+     * const result = await palveron.verify({ prompt: 'User input here' });
+     * if (result.decision === 'BLOCKED') {
+     *   throw new Error(result.reason);
+     * }
+     * ```
+     */
+    verify(request: VerifyRequest): Promise<VerifyResponse>;
+    /**
+     * Quick verification for text-only prompts.
+     *
+     * @example
+     * ```typescript
+     * const result = await palveron.check('Is this prompt safe?');
+     * console.log(result.decision); // 'ALLOWED'
+     * ```
+     */
+    check(prompt: string): Promise<VerifyResponse>;
+    /**
+     * Verify a prompt with a file attachment.
+     * Reads the file, Base64-encodes it, and sends it with the correct MIME type.
+     * Node.js only — use verify() with pre-encoded data in browsers.
+     *
+     * @example
+     * ```typescript
+     * const result = await palveron.verifyWithFile(
+     *   'Analyze this document',
+     *   '/path/to/report.pdf'
+     * );
+     * ```
+     */
+    verifyWithFile(prompt: string, filePath: string): Promise<VerifyResponse>;
+    /**
+     * List all active policies for the project.
+     */
+    listPolicies(env?: string): Promise<PolicyListResponse>;
+    /**
+     * Check gateway health status.
+     */
+    health(): Promise<HealthResponse>;
+    /**
+     * Get SDK and connection diagnostics.
+     */
+    diagnostics(): {
+        sdkVersion: string;
+        baseUrl: string;
+        timeout: number;
+        maxRetries: number;
+        circuitState: string;
+    };
+    private request;
+    private backoffDelay;
+    private sleep;
+    private generateRequestId;
+    private inferMimeType;
+}
+/**
+ * Create a Palveron client instance.
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from '@palveron/sdk';
+ *
+ * const palveron = createClient({
+ *   apiKey: process.env.PALVERON_API_KEY!,
+ *   baseUrl: 'https://gateway.acme.corp:8080', // on-prem
+ * });
+ *
+ * const result = await palveron.verify({ prompt: userInput });
+ * ```
+ */
+declare function createClient(config: PalveronConfig): Palveron;
+
+export { type Attachment, type Decision, type Finding, type HealthResponse, Palveron, PalveronAuthenticationError, PalveronCircuitOpenError, type PalveronConfig, PalveronError, type PalveronLogger, PalveronRateLimitError, PalveronTimeoutError, PalveronValidationError, type PolicyListResponse, type RequestContext, type RiskLevel, type Sensitivity, type VerifyRequest, type VerifyResponse, createClient, Palveron as default };

package/dist/index.js

@@ -0,0 +1,444 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Palveron: () => Palveron,
+  PalveronAuthenticationError: () => PalveronAuthenticationError,
+  PalveronCircuitOpenError: () => PalveronCircuitOpenError,
+  PalveronError: () => PalveronError,
+  PalveronRateLimitError: () => PalveronRateLimitError,
+  PalveronTimeoutError: () => PalveronTimeoutError,
+  PalveronValidationError: () => PalveronValidationError,
+  createClient: () => createClient,
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+var PalveronError = class extends Error {
+  code;
+  statusCode;
+  requestId;
+  retryable;
+  constructor(message, opts) {
+    super(message);
+    this.name = "PalveronError";
+    this.code = opts.code;
+    this.statusCode = opts.statusCode;
+    this.requestId = opts.requestId ?? null;
+    this.retryable = opts.retryable ?? false;
+  }
+};
+var PalveronAuthenticationError = class extends PalveronError {
+  constructor(message, requestId) {
+    super(message, { code: "AUTHENTICATION_FAILED", statusCode: 401, requestId, retryable: false });
+    this.name = "PalveronAuthenticationError";
+  }
+};
+var PalveronRateLimitError = class extends PalveronError {
+  retryAfterMs;
+  constructor(message, retryAfterMs, requestId) {
+    super(message, { code: "RATE_LIMITED", statusCode: 429, requestId, retryable: true });
+    this.name = "PalveronRateLimitError";
+    this.retryAfterMs = retryAfterMs;
+  }
+};
+var PalveronValidationError = class extends PalveronError {
+  field;
+  constructor(message, field, requestId) {
+    super(message, { code: "VALIDATION_ERROR", statusCode: 400, requestId, retryable: false });
+    this.name = "PalveronValidationError";
+    this.field = field ?? null;
+  }
+};
+var PalveronCircuitOpenError = class extends PalveronError {
+  constructor() {
+    super("Circuit breaker is open \u2014 too many consecutive failures. Retry later.", {
+      code: "CIRCUIT_OPEN",
+      statusCode: 503,
+      retryable: false
+    });
+    this.name = "PalveronCircuitOpenError";
+  }
+};
+var PalveronTimeoutError = class extends PalveronError {
+  constructor(timeoutMs, requestId) {
+    super(`Request timed out after ${timeoutMs}ms`, {
+      code: "TIMEOUT",
+      statusCode: 408,
+      requestId,
+      retryable: true
+    });
+    this.name = "PalveronTimeoutError";
+  }
+};
+var CircuitBreaker = class {
+  constructor(threshold, cooldownMs) {
+    this.threshold = threshold;
+    this.cooldownMs = cooldownMs;
+  }
+  threshold;
+  cooldownMs;
+  failures = 0;
+  lastFailure = 0;
+  state = "closed";
+  canRequest() {
+    if (this.state === "closed") return true;
+    if (this.state === "open") {
+      if (Date.now() - this.lastFailure >= this.cooldownMs) {
+        this.state = "half-open";
+        return true;
+      }
+      return false;
+    }
+    return true;
+  }
+  onSuccess() {
+    this.failures = 0;
+    this.state = "closed";
+  }
+  onFailure() {
+    this.failures++;
+    this.lastFailure = Date.now();
+    if (this.failures >= this.threshold) {
+      this.state = "open";
+    }
+  }
+  getState() {
+    return this.state;
+  }
+};
+var DEFAULT_BASE_URL = "https://gateway.palveron.com";
+var DEFAULT_TIMEOUT = 3e4;
+var DEFAULT_MAX_RETRIES = 3;
+var DEFAULT_RETRY_BASE_DELAY = 500;
+var SDK_VERSION = "1.0.0";
+var Palveron = class {
+  config;
+  circuit;
+  constructor(config) {
+    if (!config.apiKey) throw new PalveronValidationError("apiKey is required");
+    this.config = {
+      apiKey: config.apiKey,
+      baseUrl: (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, ""),
+      timeout: config.timeout ?? DEFAULT_TIMEOUT,
+      maxRetries: config.maxRetries ?? DEFAULT_MAX_RETRIES,
+      retryBaseDelay: config.retryBaseDelay ?? DEFAULT_RETRY_BASE_DELAY,
+      logger: config.logger,
+      headers: config.headers
+    };
+    this.circuit = new CircuitBreaker(
+      config.circuitBreakerThreshold ?? 5,
+      config.circuitBreakerCooldown ?? 3e4
+    );
+  }
+  // ── Core: Verify ────────────────────────────────────────
+  /**
+   * Send a governance verification request.
+   * This is the primary method — every LLM call should go through this.
+   *
+   * @example
+   * ```typescript
+   * const result = await palveron.verify({ prompt: 'User input here' });
+   * if (result.decision === 'BLOCKED') {
+   *   throw new Error(result.reason);
+   * }
+   * ```
+   */
+  async verify(request) {
+    const body = {
+      prompt: request.prompt,
+      extracted_text: request.extractedText,
+      metadata: request.metadata,
+      attachments: request.attachments?.map((a) => ({
+        content_type: a.contentType,
+        data: a.data,
+        filename: a.filename,
+        metadata: a.metadata
+      })),
+      context: request.context ? {
+        mcp_server: request.context.mcpServer,
+        tool_name: request.context.toolName,
+        chain_depth: request.context.chainDepth,
+        source_system: request.context.sourceSystem,
+        session_id: request.context.sessionId
+      } : void 0
+    };
+    const start = Date.now();
+    const raw = await this.request("POST", "/api/v1/verify", body);
+    const latency = Date.now() - start;
+    return {
+      decision: raw.decision ?? "ERROR",
+      output: raw.output ?? "",
+      reason: raw.reason ?? "",
+      traceId: raw.trace_id ?? "",
+      integrityHash: raw.integrity_hash ?? "",
+      shouldAnchor: raw.should_anchor ?? false,
+      flareStatus: raw.flare_status ?? "",
+      flareTxHash: raw.flare_tx_hash ?? null,
+      contentType: raw.content_type ?? "text",
+      findings: raw.findings ?? [],
+      latencyMs: latency
+    };
+  }
+  // ── Convenience: Quick verify (string-only) ─────────────
+  /**
+   * Quick verification for text-only prompts.
+   *
+   * @example
+   * ```typescript
+   * const result = await palveron.check('Is this prompt safe?');
+   * console.log(result.decision); // 'ALLOWED'
+   * ```
+   */
+  async check(prompt) {
+    return this.verify({ prompt });
+  }
+  // ── Convenience: Verify with file ───────────────────────
+  /**
+   * Verify a prompt with a file attachment.
+   * Reads the file, Base64-encodes it, and sends it with the correct MIME type.
+   * Node.js only — use verify() with pre-encoded data in browsers.
+   *
+   * @example
+   * ```typescript
+   * const result = await palveron.verifyWithFile(
+   *   'Analyze this document',
+   *   '/path/to/report.pdf'
+   * );
+   * ```
+   */
+  async verifyWithFile(prompt, filePath) {
+    const { readFile } = await import("fs/promises");
+    const { basename } = await import("path");
+    const buffer = await readFile(filePath);
+    const base64 = buffer.toString("base64");
+    const filename = basename(filePath);
+    const contentType = this.inferMimeType(filename);
+    return this.verify({
+      prompt,
+      attachments: [{ contentType, data: base64, filename }]
+    });
+  }
+  // ── Policies ────────────────────────────────────────────
+  /**
+   * List all active policies for the project.
+   */
+  async listPolicies(env = "prod") {
+    return this.request("GET", `/api/v1/policies?env=${env}`);
+  }
+  // ── Health ──────────────────────────────────────────────
+  /**
+   * Check gateway health status.
+   */
+  async health() {
+    return this.request("GET", "/health");
+  }
+  // ── Diagnostics ─────────────────────────────────────────
+  /**
+   * Get SDK and connection diagnostics.
+   */
+  diagnostics() {
+    return {
+      sdkVersion: SDK_VERSION,
+      baseUrl: this.config.baseUrl,
+      timeout: this.config.timeout,
+      maxRetries: this.config.maxRetries,
+      circuitState: this.circuit.getState()
+    };
+  }
+  // ─── Internal: HTTP with retry + circuit breaker ────────
+  async request(method, path, body) {
+    if (!this.circuit.canRequest()) {
+      throw new PalveronCircuitOpenError();
+    }
+    let lastError = null;
+    const maxAttempts = this.config.maxRetries + 1;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      if (attempt > 0) {
+        const delay = this.backoffDelay(attempt);
+        this.config.logger?.debug(`Retry attempt ${attempt}/${this.config.maxRetries}`, { delay, path });
+        await this.sleep(delay);
+      }
+      const requestId = this.generateRequestId();
+      try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.config.timeout);
+        const headers = {
+          "Authorization": `Bearer ${this.config.apiKey}`,
+          "Content-Type": "application/json",
+          "Accept": "application/json",
+          "User-Agent": `palveron-sdk-typescript/${SDK_VERSION}`,
+          "X-Request-ID": requestId,
+          ...this.config.headers
+        };
+        const response = await fetch(`${this.config.baseUrl}${path}`, {
+          method,
+          headers,
+          body: body ? JSON.stringify(body) : void 0,
+          signal: controller.signal
+        });
+        clearTimeout(timer);
+        const responseRequestId = response.headers.get("x-request-id") ?? requestId;
+        if (response.ok) {
+          this.circuit.onSuccess();
+          return await response.json();
+        }
+        if (response.status === 401) {
+          this.circuit.onSuccess();
+          throw new PalveronAuthenticationError(
+            "Invalid API key or expired token",
+            responseRequestId
+          );
+        }
+        if (response.status === 429) {
+          const retryAfter = parseInt(response.headers.get("retry-after") ?? "5", 10) * 1e3;
+          throw new PalveronRateLimitError(
+            "Rate limit exceeded",
+            retryAfter,
+            responseRequestId
+          );
+        }
+        if (response.status === 400) {
+          const errorBody2 = await response.json().catch(() => ({}));
+          throw new PalveronValidationError(
+            errorBody2.error ?? "Invalid request",
+            errorBody2.field,
+            responseRequestId
+          );
+        }
+        if (response.status >= 500) {
+          this.circuit.onFailure();
+          const errorBody2 = await response.text().catch(() => "");
+          lastError = new PalveronError(
+            `Server error: ${response.status} ${response.statusText}`,
+            { code: "SERVER_ERROR", statusCode: response.status, requestId: responseRequestId, retryable: true }
+          );
+          this.config.logger?.warn(`Server error on attempt ${attempt + 1}`, {
+            status: response.status,
+            requestId: responseRequestId,
+            body: errorBody2.slice(0, 200)
+          });
+          continue;
+        }
+        const errorBody = await response.json().catch(() => ({}));
+        throw new PalveronError(
+          errorBody.error ?? `HTTP ${response.status}`,
+          { code: "CLIENT_ERROR", statusCode: response.status, requestId: responseRequestId, retryable: false }
+        );
+      } catch (error) {
+        if (error instanceof PalveronError && !error.retryable) throw error;
+        if (error instanceof DOMException && error.name === "AbortError") {
+          this.circuit.onFailure();
+          lastError = new PalveronTimeoutError(this.config.timeout, requestId);
+          continue;
+        }
+        if (error instanceof TypeError && error.message.includes("fetch")) {
+          this.circuit.onFailure();
+          lastError = new PalveronError("Network error \u2014 could not reach gateway", {
+            code: "NETWORK_ERROR",
+            statusCode: 0,
+            requestId,
+            retryable: true
+          });
+          continue;
+        }
+        if (error instanceof PalveronError) {
+          lastError = error;
+          continue;
+        }
+        throw error;
+      }
+    }
+    throw lastError ?? new PalveronError("Max retries exceeded", {
+      code: "MAX_RETRIES",
+      statusCode: 0,
+      retryable: false
+    });
+  }
+  // ─── Helpers ────────────────────────────────────────────
+  backoffDelay(attempt) {
+    const base = this.config.retryBaseDelay * Math.pow(2, attempt - 1);
+    const jitter = base * 0.2 * Math.random();
+    return Math.min(base + jitter, 3e4);
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  generateRequestId() {
+    const ts = Date.now().toString(36);
+    const rand = Math.random().toString(36).slice(2, 8);
+    return `pv_${ts}_${rand}`;
+  }
+  inferMimeType(filename) {
+    const ext = filename.split(".").pop()?.toLowerCase();
+    const map = {
+      png: "image/png",
+      jpg: "image/jpeg",
+      jpeg: "image/jpeg",
+      gif: "image/gif",
+      webp: "image/webp",
+      svg: "image/svg+xml",
+      pdf: "application/pdf",
+      wav: "audio/wav",
+      mp3: "audio/mpeg",
+      ogg: "audio/ogg",
+      mp4: "video/mp4",
+      py: "text/x-python",
+      js: "text/javascript",
+      ts: "text/typescript",
+      rs: "text/x-rust",
+      go: "text/x-go",
+      java: "text/x-java",
+      c: "text/x-c",
+      cpp: "text/x-c++",
+      txt: "text/plain",
+      json: "application/json",
+      csv: "text/csv",
+      xml: "application/xml"
+    };
+    return map[ext ?? ""] ?? "application/octet-stream";
+  }
+};
+function createClient(config) {
+  return new Palveron(config);
+}
+var index_default = Palveron;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Palveron,
+  PalveronAuthenticationError,
+  PalveronCircuitOpenError,
+  PalveronError,
+  PalveronRateLimitError,
+  PalveronTimeoutError,
+  PalveronValidationError,
+  createClient
+});
+//# sourceMappingURL=index.js.map