@intelmesh/sdk 0.1.0

package/src/client/errors.ts

@@ -0,0 +1,171 @@
+// ---------------------------------------------------------------------------
+// Typed error hierarchy for IntelMesh API responses
+// ---------------------------------------------------------------------------
+
+/** Base error for all IntelMesh SDK errors. */
+export class IntelMeshError extends Error {
+  /** HTTP status code, if applicable. */
+  readonly status: number;
+  /** Machine-readable error code from the API. */
+  readonly code: string;
+
+  constructor(message: string, status: number, code: string) {
+    super(message);
+    this.name = 'IntelMeshError';
+    this.status = status;
+    this.code = code;
+  }
+}
+
+/** 400 — The request was malformed or invalid. */
+export class ValidationError extends IntelMeshError {
+  constructor(message: string, code = 'VALIDATION_ERROR') {
+    super(message, 400, code);
+    this.name = 'ValidationError';
+  }
+}
+
+/** 404 — The requested resource was not found. */
+export class NotFoundError extends IntelMeshError {
+  constructor(message: string, code = 'NOT_FOUND') {
+    super(message, 404, code);
+    this.name = 'NotFoundError';
+  }
+}
+
+/** 401 — Authentication failed or missing. */
+export class UnauthorizedError extends IntelMeshError {
+  constructor(message: string, code = 'UNAUTHORIZED') {
+    super(message, 401, code);
+    this.name = 'UnauthorizedError';
+  }
+}
+
+/** 403 — Authenticated but insufficient permissions. */
+export class ForbiddenError extends IntelMeshError {
+  constructor(message: string, code = 'FORBIDDEN') {
+    super(message, 403, code);
+    this.name = 'ForbiddenError';
+  }
+}
+
+/** 500 — Internal server error. */
+export class InternalError extends IntelMeshError {
+  constructor(message: string, code = 'INTERNAL_ERROR') {
+    super(message, 500, code);
+    this.name = 'InternalError';
+  }
+}
+
+/** 503 — Service temporarily unavailable. */
+export class UnavailableError extends IntelMeshError {
+  constructor(message: string, code = 'UNAVAILABLE') {
+    super(message, 503, code);
+    this.name = 'UnavailableError';
+  }
+}
+
+/** Network-level failure (no HTTP response received). */
+export class NetworkError extends IntelMeshError {
+  constructor(message: string) {
+    super(message, 0, 'NETWORK_ERROR');
+    this.name = 'NetworkError';
+  }
+}
+
+/** Failed to parse the API response body. */
+export class ParseError extends IntelMeshError {
+  constructor(message: string) {
+    super(message, 0, 'PARSE_ERROR');
+    this.name = 'ParseError';
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Type guard helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Checks if an error is a NotFoundError.
+ * @param error - The error to check.
+ * @returns True if the error is a NotFoundError.
+ */
+export function isNotFound(error: unknown): error is NotFoundError {
+  return error instanceof NotFoundError;
+}
+
+/**
+ * Checks if an error is a ValidationError.
+ * @param error - The error to check.
+ * @returns True if the error is a ValidationError.
+ */
+export function isValidation(error: unknown): error is ValidationError {
+  return error instanceof ValidationError;
+}
+
+/**
+ * Checks if an error is an UnauthorizedError.
+ * @param error - The error to check.
+ * @returns True if the error is an UnauthorizedError.
+ */
+export function isUnauthorized(error: unknown): error is UnauthorizedError {
+  return error instanceof UnauthorizedError;
+}
+
+/**
+ * Checks if an error is a ForbiddenError.
+ * @param error - The error to check.
+ * @returns True if the error is a ForbiddenError.
+ */
+export function isForbidden(error: unknown): error is ForbiddenError {
+  return error instanceof ForbiddenError;
+}
+
+/**
+ * Checks if an error is a NetworkError.
+ * @param error - The error to check.
+ * @returns True if the error is a NetworkError.
+ */
+export function isNetwork(error: unknown): error is NetworkError {
+  return error instanceof NetworkError;
+}
+
+/**
+ * Checks if an error is any IntelMeshError.
+ * @param error - The error to check.
+ * @returns True if the error is an IntelMeshError.
+ */
+export function isIntelMeshError(error: unknown): error is IntelMeshError {
+  return error instanceof IntelMeshError;
+}
+
+// ---------------------------------------------------------------------------
+// Status code to error mapping
+// ---------------------------------------------------------------------------
+
+/**
+ * Maps an HTTP status code and error body to a typed error.
+ * @param status - The HTTP status code.
+ * @param message - The error message from the API.
+ * @param code - The machine-readable error code from the API.
+ * @returns The appropriate typed error instance.
+ */
+export function mapStatusToError(status: number, message: string, code: string): IntelMeshError {
+  switch (status) {
+    case 400:
+      return new ValidationError(message, code);
+    case 401:
+      return new UnauthorizedError(message, code);
+    case 403:
+      return new ForbiddenError(message, code);
+    case 404:
+      return new NotFoundError(message, code);
+    case 503:
+      return new UnavailableError(message, code);
+    default:
+      if (status >= 500) {
+        return new InternalError(message, code);
+      }
+      return new IntelMeshError(message, status, code);
+  }
+}

package/src/client/http.ts

@@ -0,0 +1,209 @@
+// ---------------------------------------------------------------------------
+// Base HTTP client — fetch wrapper with auth, JSON parsing, error mapping
+// ---------------------------------------------------------------------------
+
+import type { ClientConfig, ErrorResponse, SuccessResponse } from '../types.js';
+import { mapStatusToError, NetworkError, ParseError } from './errors.js';
+
+/** HTTP methods supported by the client. */
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
+
+/** Options for a single HTTP request. */
+interface RequestOptions {
+  readonly method: HttpMethod;
+  readonly path: string;
+  readonly body?: unknown;
+  readonly query?: Readonly<Record<string, string | number | undefined>>;
+  readonly signal?: AbortSignal;
+}
+
+/** Default request timeout in milliseconds. */
+const DEFAULT_TIMEOUT = 30_000;
+
+/**
+ * Low-level HTTP client for the IntelMesh API.
+ * Handles authentication, serialization, and error mapping.
+ */
+export class HttpClient {
+  private readonly baseUrl: string;
+  private readonly apiKey: string;
+  private readonly timeout: number;
+  private readonly fetchFn: typeof globalThis.fetch;
+
+  constructor(config: ClientConfig) {
+    this.baseUrl = config.baseUrl.replace(/\/+$/, '');
+    this.apiKey = config.apiKey;
+    this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+    this.fetchFn = config.fetch ?? globalThis.fetch.bind(globalThis);
+  }
+
+  /**
+   * Executes a GET request and returns the parsed data.
+   * @param path - The API path.
+   * @param query - Optional query parameters.
+   * @returns The response data of type T.
+   */
+  async get<T>(path: string, query?: RequestOptions['query']): Promise<T> {
+    return this.request<T>({ method: 'GET', path, query });
+  }
+
+  /**
+   * Executes a POST request and returns the parsed data.
+   * @param path - The API path.
+   * @param body - The request body.
+   * @returns The response data of type T.
+   */
+  async post<T>(path: string, body: unknown): Promise<T> {
+    return this.request<T>({ method: 'POST', path, body });
+  }
+
+  /**
+   * Executes a PUT request and returns the parsed data.
+   * @param path - The API path.
+   * @param body - The request body.
+   * @returns The response data of type T.
+   */
+  async put<T>(path: string, body: unknown): Promise<T> {
+    return this.request<T>({ method: 'PUT', path, body });
+  }
+
+  /**
+   * Executes a DELETE request and returns the parsed data.
+   * @param path - The API path.
+   * @returns The response data of type T.
+   */
+  async delete<T>(path: string): Promise<T> {
+    return this.request<T>({ method: 'DELETE', path });
+  }
+
+  /**
+   * Builds the full URL with query parameters.
+   * @param path - The API path.
+   * @param query - Optional query parameters.
+   * @returns The full URL string.
+   */
+  private buildUrl(path: string, query?: RequestOptions['query']): string {
+    const url = new URL(`${this.baseUrl}${path}`);
+    if (query) {
+      for (const [key, value] of Object.entries(query)) {
+        if (value !== undefined) {
+          url.searchParams.set(key, String(value));
+        }
+      }
+    }
+    return url.toString();
+  }
+
+  /**
+   * Executes an HTTP request with timeout, auth, and error handling.
+   * @param options - The request options.
+   * @returns The parsed response data.
+   */
+  private async request<T>(options: RequestOptions): Promise<T> {
+    const url = this.buildUrl(options.path, options.query);
+    const controller = new AbortController();
+    const timer = setTimeout(() => {
+      controller.abort();
+    }, this.timeout);
+
+    try {
+      const response = await this.executeFetch(url, options, controller.signal);
+      return await this.handleResponse<T>(response);
+    } catch (error: unknown) {
+      throw this.wrapError(error);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  /**
+   * Calls fetch with the configured headers and body.
+   * @param url - The full URL.
+   * @param options - The request options.
+   * @param signal - The abort signal.
+   * @returns The fetch Response.
+   */
+  private async executeFetch(
+    url: string,
+    options: RequestOptions,
+    signal: AbortSignal,
+  ): Promise<Response> {
+    const headers: Record<string, string> = {
+      Authorization: `Bearer ${this.apiKey}`,
+      Accept: 'application/json',
+    };
+
+    if (options.body !== undefined) {
+      headers['Content-Type'] = 'application/json';
+    }
+
+    return this.fetchFn(url, {
+      method: options.method,
+      headers,
+      body: options.body !== undefined ? JSON.stringify(options.body) : undefined,
+      signal,
+    });
+  }
+
+  /**
+   * Parses the response and throws typed errors for non-2xx status.
+   * @param response - The fetch Response.
+   * @returns The parsed data.
+   */
+  private async handleResponse<T>(response: Response): Promise<T> {
+    const text = await response.text();
+
+    if (!response.ok) {
+      this.throwApiError(response.status, text);
+    }
+
+    const parsed = this.parseJson(text) as SuccessResponse<T>;
+    return parsed.data;
+  }
+
+  /**
+   * Parses and throws an API error from the response body.
+   * @param status - The HTTP status code.
+   * @param text - The raw response body.
+   */
+  private throwApiError(status: number, text: string): never {
+    try {
+      const body = JSON.parse(text) as ErrorResponse;
+      throw mapStatusToError(status, body.error.message, body.error.code);
+    } catch (error: unknown) {
+      if (error instanceof Error && 'status' in error) throw error;
+      throw mapStatusToError(status, text || `HTTP ${String(status)}`, 'UNKNOWN');
+    }
+  }
+
+  /**
+   * Safely parses JSON with a typed parse error.
+   * @param text - The raw JSON text.
+   * @returns The parsed JSON object.
+   */
+  private parseJson(text: string): unknown {
+    try {
+      return JSON.parse(text) as unknown;
+    } catch {
+      throw new ParseError(`Failed to parse response: ${text.slice(0, 200)}`);
+    }
+  }
+
+  /**
+   * Wraps unexpected errors into NetworkError.
+   * @param error - The caught error.
+   * @returns A NetworkError or the original error.
+   */
+  private wrapError(error: unknown): unknown {
+    if (error instanceof Error && error.name === 'AbortError') {
+      return new NetworkError('Request timed out');
+    }
+    if (error instanceof Error && 'status' in error) {
+      return error;
+    }
+    if (error instanceof Error) {
+      return new NetworkError(error.message);
+    }
+    return new NetworkError('Unknown network error');
+  }
+}

package/src/client/intelmesh.ts

@@ -0,0 +1,57 @@
+// ---------------------------------------------------------------------------
+// Main IntelMesh client — facade that creates resource instances
+// ---------------------------------------------------------------------------
+
+import type { ClientConfig } from '../types.js';
+import { HttpClient } from './http.js';
+import { APIKeys } from '../resources/apikeys.js';
+import { Audit } from '../resources/audit.js';
+import { Evaluations } from '../resources/evaluations.js';
+import { Events } from '../resources/events.js';
+import { Lists } from '../resources/lists.js';
+import { Phases } from '../resources/phases.js';
+import { Rules } from '../resources/rules.js';
+import { Scores } from '../resources/scores.js';
+import { Scopes } from '../resources/scopes.js';
+
+/**
+ * Main IntelMesh SDK client.
+ * Provides access to all API resources through typed sub-clients.
+ */
+export class IntelMesh {
+  /** Event ingestion and simulation. */
+  readonly events: Events;
+  /** Rule management and versioning. */
+  readonly rules: Rules;
+  /** Pipeline phase management. */
+  readonly phases: Phases;
+  /** Scope management. */
+  readonly scopes: Scopes;
+  /** Named list management. */
+  readonly lists: Lists;
+  /** Score management. */
+  readonly scores: Scores;
+  /** API key management. */
+  readonly apiKeys: APIKeys;
+  /** Evaluation log inspection. */
+  readonly evaluations: Evaluations;
+  /** Audit log access. */
+  readonly audit: Audit;
+
+  /**
+   * Creates a new IntelMesh client instance.
+   * @param config - Client configuration with baseUrl and apiKey.
+   */
+  constructor(config: ClientConfig) {
+    const http = new HttpClient(config);
+    this.events = new Events(http);
+    this.rules = new Rules(http);
+    this.phases = new Phases(http);
+    this.scopes = new Scopes(http);
+    this.lists = new Lists(http);
+    this.scores = new Scores(http);
+    this.apiKeys = new APIKeys(http);
+    this.evaluations = new Evaluations(http);
+    this.audit = new Audit(http);
+  }
+}

package/src/client/pagination.ts

@@ -0,0 +1,50 @@
+// ---------------------------------------------------------------------------
+// Async cursor-based pagination iterator
+// ---------------------------------------------------------------------------
+
+import type { PaginatedResponse, PaginationParams } from '../types.js';
+
+/** Function that fetches a single page of results. */
+type PageFetcher<T> = (params: PaginationParams) => Promise<PaginatedResponse<T>>;
+
+/**
+ * Creates an async iterator that automatically follows cursor pagination.
+ * @param fetcher - Function to fetch a single page.
+ * @param params - Initial pagination parameters.
+ * @yields {T} Individual items from paginated responses.
+ * @returns An async iterable of individual items.
+ */
+export async function* paginate<T>(
+  fetcher: PageFetcher<T>,
+  params: PaginationParams = {},
+): AsyncGenerator<T, void, undefined> {
+  let cursor = params.cursor;
+  let hasMore = true;
+
+  while (hasMore) {
+    const page = await fetcher({ cursor, limit: params.limit });
+
+    for (const item of page.items) {
+      yield item;
+    }
+
+    if (page.next_cursor) {
+      cursor = page.next_cursor;
+    } else {
+      hasMore = false;
+    }
+  }
+}
+
+/**
+ * Collects all items from an async iterator into an array.
+ * @param iter - The async iterable to collect from.
+ * @returns An array of all items.
+ */
+export async function collectAll<T>(iter: AsyncIterable<T>): Promise<T[]> {
+  const results: T[] = [];
+  for await (const item of iter) {
+    results.push(item);
+  }
+  return results;
+}

package/src/generated/types.ts

@@ -0,0 +1,11 @@
+// ---------------------------------------------------------------------------
+// Auto-generated types placeholder
+// ---------------------------------------------------------------------------
+// The swagger.json is Swagger 2.0 format, which openapi-typescript does not support.
+// Once the API spec is converted to OpenAPI 3.x, regenerate with:
+//   npx openapi-typescript ../docs/swagger.json -o src/generated/types.ts
+//
+// In the meantime, all API types are manually defined in src/types.ts
+// ---------------------------------------------------------------------------
+
+export type GeneratedPlaceholder = Record<string, never>;

package/src/index.ts

@@ -0,0 +1,106 @@
+// ---------------------------------------------------------------------------
+// @intelmesh/sdk — Public API exports
+// ---------------------------------------------------------------------------
+
+// Main client
+export { IntelMesh } from './client/intelmesh.js';
+
+// HTTP client (for advanced usage)
+export { HttpClient } from './client/http.js';
+
+// Error types and helpers
+export {
+  IntelMeshError,
+  ValidationError,
+  NotFoundError,
+  UnauthorizedError,
+  ForbiddenError,
+  InternalError,
+  UnavailableError,
+  NetworkError,
+  ParseError,
+  isNotFound,
+  isValidation,
+  isUnauthorized,
+  isForbidden,
+  isNetwork,
+  isIntelMeshError,
+  mapStatusToError,
+} from './client/errors.js';
+
+// Pagination
+export { paginate, collectAll } from './client/pagination.js';
+
+// Resources
+export { Events } from './resources/events.js';
+export { Rules } from './resources/rules.js';
+export { Phases } from './resources/phases.js';
+export { Scopes } from './resources/scopes.js';
+export { Lists } from './resources/lists.js';
+export { Scores } from './resources/scores.js';
+export { APIKeys } from './resources/apikeys.js';
+export { Evaluations } from './resources/evaluations.js';
+export { Audit } from './resources/audit.js';
+
+// Builders
+export { EventBuilder } from './builders/event.js';
+export { RuleBuilder } from './builders/rule.js';
+
+// Provision
+export { Provisioner } from './provision/index.js';
+export { ProvisionRuleBuilder } from './provision/index.js';
+
+// Testkit
+export { Harness, withHarness } from './testkit/index.js';
+export type { HarnessConfig } from './testkit/index.js';
+export { EventAssertion } from './testkit/index.js';
+
+// Types
+export type {
+  // Core domain
+  Severity,
+  Flow,
+  Decision,
+  ScoreOperation,
+  ListMutation,
+  Actions,
+  Rule,
+  RuleVersion,
+  Phase,
+  Scope,
+  List,
+  Score,
+  APIKey,
+  EvaluationLog,
+  RuleTrace,
+  PhaseTrace,
+  PipelineTrace,
+  // Requests
+  IngestRequest,
+  CreateRuleRequest,
+  UpdateRuleRequest,
+  CreatePhaseRequest,
+  UpdatePhaseRequest,
+  CreateScopeRequest,
+  UpdateScopeRequest,
+  CreateListRequest,
+  UpdateListRequest,
+  AddItemsRequest,
+  BulkImportRequest,
+  SetScoreRequest,
+  CreateAPIKeyRequest,
+  CreateAPIKeyResponse,
+  UpdateAPIKeyRequest,
+  // Results
+  IngestResult,
+  Mutation,
+  // Pagination
+  PaginatedResponse,
+  PaginationParams,
+  // Envelope
+  SuccessResponse,
+  ErrorBody,
+  ErrorResponse,
+  // Config
+  ClientConfig,
+} from './types.js';

package/src/provision/index.ts

@@ -0,0 +1,6 @@
+// ---------------------------------------------------------------------------
+// Provision module — public exports
+// ---------------------------------------------------------------------------
+
+export { Provisioner } from './provisioner.js';
+export { ProvisionRuleBuilder } from './rule-builder.js';