@intelmesh/sdk 0.1.0

package/src/provision/provisioner.ts

@@ -0,0 +1,326 @@
+// ---------------------------------------------------------------------------
+// Provisioner — declarative resource provisioning for IntelMesh
+// Mirrors the Go SDK's provision.Provisioner exactly.
+// ---------------------------------------------------------------------------
+
+import type { IntelMesh } from '../client/intelmesh.js';
+import { ProvisionRuleBuilder } from './rule-builder.js';
+
+/** Resource kinds in provisioning order. */
+const STEP_PHASE = 0 as const;
+const STEP_SCOPE = 1 as const;
+const STEP_LIST = 2 as const;
+const STEP_RULE = 3 as const;
+
+type StepKind = typeof STEP_PHASE | typeof STEP_SCOPE | typeof STEP_LIST | typeof STEP_RULE;
+
+/** A single resource to create during apply. */
+interface Step {
+  readonly kind: StepKind;
+  readonly name: string;
+  readonly position: number;
+  readonly applicableWhen: string;
+  readonly jsonPath: string;
+  readonly ruleBuilder: ProvisionRuleBuilder | undefined;
+}
+
+/**
+ * Builds and executes a declarative resource plan against the IntelMesh API.
+ * Resources are created in dependency order (phases, scopes, lists, rules)
+ * and torn down in reverse.
+ */
+export class Provisioner {
+  private readonly client: IntelMesh;
+  private readonly steps: Step[] = [];
+
+  private readonly phases = new Map<string, string>();
+  private readonly scopes = new Map<string, string>();
+  private readonly lists = new Map<string, string>();
+  private readonly rules = new Map<string, string>();
+
+  /**
+   * Creates a new Provisioner backed by the given SDK client.
+   * @param client - The IntelMesh client instance.
+   */
+  constructor(client: IntelMesh) {
+    this.client = client;
+  }
+
+  /**
+   * Registers a pipeline phase to be created.
+   * @param name - The phase name.
+   * @param position - The phase position (execution order).
+   * @returns This provisioner for chaining.
+   */
+  phase(name: string, position: number): this {
+    this.steps.push({
+      kind: STEP_PHASE,
+      name,
+      position,
+      applicableWhen: '',
+      jsonPath: '',
+      ruleBuilder: undefined,
+    });
+    return this;
+  }
+
+  /**
+   * Registers a pipeline phase with an applicable_when CEL expression.
+   * @param name - The phase name.
+   * @param position - The phase position (execution order).
+   * @param applicableWhen - CEL expression controlling when this phase runs.
+   * @returns This provisioner for chaining.
+   */
+  phaseWithFilter(name: string, position: number, applicableWhen: string): this {
+    this.steps.push({
+      kind: STEP_PHASE,
+      name,
+      position,
+      applicableWhen,
+      jsonPath: '',
+      ruleBuilder: undefined,
+    });
+    return this;
+  }
+
+  /**
+   * Registers a scope to be created.
+   * @param name - The scope name.
+   * @param jsonPath - The JSON path expression.
+   * @returns This provisioner for chaining.
+   */
+  scope(name: string, jsonPath: string): this {
+    this.steps.push({
+      kind: STEP_SCOPE,
+      name,
+      position: 0,
+      applicableWhen: '',
+      jsonPath,
+      ruleBuilder: undefined,
+    });
+    return this;
+  }
+
+  /**
+   * Registers a named list to be created.
+   * @param name - The list name.
+   * @returns This provisioner for chaining.
+   */
+  list(name: string): this {
+    this.steps.push({
+      kind: STEP_LIST,
+      name,
+      position: 0,
+      applicableWhen: '',
+      jsonPath: '',
+      ruleBuilder: undefined,
+    });
+    return this;
+  }
+
+  /**
+   * Starts building a rule and returns a ProvisionRuleBuilder.
+   * @param name - The rule name.
+   * @returns A rule builder for chaining.
+   */
+  rule(name: string): ProvisionRuleBuilder {
+    return new ProvisionRuleBuilder(this, name);
+  }
+
+  /**
+   * Adds a completed rule step from the rule builder.
+   * @param rb - The completed rule builder.
+   * @returns This provisioner for chaining.
+   * @internal
+   */
+  _addRuleStep(rb: ProvisionRuleBuilder): this {
+    this.steps.push({
+      kind: STEP_RULE,
+      name: rb.ruleName,
+      position: 0,
+      applicableWhen: '',
+      jsonPath: '',
+      ruleBuilder: rb,
+    });
+    return this;
+  }
+
+  /**
+   * Creates all registered resources via the API in registration order.
+   * Throws on the first failure.
+   */
+  async apply(): Promise<void> {
+    for (const step of this.steps) {
+      await this.applyStep(step);
+    }
+  }
+
+  /**
+   * Deletes all created resources in reverse dependency order:
+   * rules, lists, scopes, phases.
+   * Collects errors but continues deleting; throws the first error at the end.
+   */
+  async teardown(): Promise<void> {
+    let firstError: Error | undefined;
+
+    const record = (err: unknown): void => {
+      if (!firstError && err instanceof Error) {
+        firstError = err;
+      }
+    };
+
+    await this.deleteAll(this.rules, (id) => this.client.rules.delete(id), record);
+    await this.deleteAll(this.lists, (id) => this.client.lists.delete(id), record);
+    await this.deleteAll(this.scopes, (id) => this.client.scopes.delete(id), record);
+    await this.deleteAll(this.phases, (id) => this.client.phases.delete(id), record);
+
+    if (firstError) {
+      throw firstError;
+    }
+  }
+
+  /**
+   * Returns the provisioned ID for the named phase.
+   * @param name - The phase name.
+   * @returns The phase ID, or empty string if not found.
+   */
+  phaseId(name: string): string {
+    return this.phases.get(name) ?? '';
+  }
+
+  /**
+   * Returns the provisioned ID for the named list.
+   * @param name - The list name.
+   * @returns The list ID, or empty string if not found.
+   */
+  listId(name: string): string {
+    return this.lists.get(name) ?? '';
+  }
+
+  /**
+   * Returns the provisioned ID for the named scope.
+   * @param name - The scope name.
+   * @returns The scope ID, or empty string if not found.
+   */
+  scopeId(name: string): string {
+    return this.scopes.get(name) ?? '';
+  }
+
+  /**
+   * Returns the provisioned ID for the named rule.
+   * @param name - The rule name.
+   * @returns The rule ID, or empty string if not found.
+   */
+  ruleId(name: string): string {
+    return this.rules.get(name) ?? '';
+  }
+
+  /**
+   * Dispatches a single step to the appropriate creator.
+   * @param step
+   */
+  private async applyStep(step: Step): Promise<void> {
+    switch (step.kind) {
+      case STEP_PHASE:
+        return this.createPhase(step);
+      case STEP_SCOPE:
+        return this.createScope(step);
+      case STEP_LIST:
+        return this.createList(step);
+      case STEP_RULE:
+        return this.createRule(step);
+    }
+  }
+
+  /**
+   * Creates a phase and stores its ID.
+   * @param step
+   */
+  private async createPhase(step: Step): Promise<void> {
+    const req: { name: string; position: number; applicable_when?: string } = {
+      name: step.name,
+      position: step.position,
+    };
+    if (step.applicableWhen) {
+      req.applicable_when = step.applicableWhen;
+    }
+    const phase = await this.client.phases.create(req);
+    this.phases.set(step.name, phase.id);
+  }
+
+  /**
+   * Creates a scope and stores its ID.
+   * @param step
+   */
+  private async createScope(step: Step): Promise<void> {
+    const scope = await this.client.scopes.create({
+      name: step.name,
+      json_path: step.jsonPath,
+    });
+    this.scopes.set(step.name, scope.id);
+  }
+
+  /**
+   * Creates a list and stores its ID.
+   * @param step
+   */
+  private async createList(step: Step): Promise<void> {
+    const list = await this.client.lists.create({
+      name: step.name,
+      description: '',
+    });
+    this.lists.set(step.name, list.id);
+  }
+
+  /**
+   * Creates a rule after resolving its phase name to an ID.
+   * @param step
+   */
+  private async createRule(step: Step): Promise<void> {
+    const rb = step.ruleBuilder;
+    if (!rb) {
+      throw new Error(`provision: rule step "${step.name}" has no builder`);
+    }
+
+    const phaseID = this.phases.get(rb.phaseName);
+    if (!phaseID) {
+      throw new Error(`provision rule "${rb.ruleName}": phase not found: ${rb.phaseName}`);
+    }
+
+    const rule = await this.client.rules.create({
+      name: rb.ruleName,
+      phase_id: phaseID,
+      priority: rb.rulePriority,
+      applicable_when: rb.applicable,
+      expression: rb.expression,
+      actions: rb.buildActions(),
+      enabled: true,
+      dry_run: rb.isDryRun,
+    });
+    this.rules.set(rb.ruleName, rule.id);
+  }
+
+  /**
+   * Deletes all resources in a map, recording errors.
+   * @param ids
+   * @param deleteFn
+   * @param record
+   */
+  private async deleteAll(
+    ids: Map<string, string>,
+    deleteFn: (id: string) => Promise<void>,
+    record: (err: unknown) => void,
+  ): Promise<void> {
+    for (const [name, id] of ids) {
+      try {
+        await deleteFn(id);
+      } catch (err: unknown) {
+        record(
+          err instanceof Error
+            ? new Error(`deleting ${name} (${id}): ${err.message}`)
+            : new Error(`deleting ${name} (${id}): unknown error`),
+        );
+      }
+    }
+  }
+}

package/src/provision/rule-builder.ts

@@ -0,0 +1,193 @@
+// ---------------------------------------------------------------------------
+// Fluent RuleBuilder for provisioner — mirrors Go SDK's provision.RuleBuilder
+// ---------------------------------------------------------------------------
+
+import type { Actions, Decision, Flow, ListMutation, ScoreOperation, Severity } from '../types.js';
+import type { Provisioner } from './provisioner.js';
+
+/** Internal mutation specification. */
+interface MutationSpec {
+  readonly mutationType: string;
+  readonly listName: string;
+  readonly valuePath: string;
+}
+
+/**
+ * Fluent builder for constructing rules within a Provisioner.
+ * Returned by `Provisioner.rule()`, completed by calling `.done()`.
+ */
+export class ProvisionRuleBuilder {
+  private readonly parent: Provisioner;
+
+  /** @internal */ readonly ruleName: string;
+  /** @internal */ phaseName = '';
+  /** @internal */ rulePriority = 0;
+  /** @internal */ applicable = '';
+  /** @internal */ expression = '';
+  /** @internal */ ruleDecision: Decision | undefined;
+  /** @internal */ ruleScore: ScoreOperation | undefined;
+  /** @internal */ ruleFlow: Flow | undefined;
+  /** @internal */ ruleMutations: MutationSpec[] = [];
+  /** @internal */ isDryRun = false;
+
+  /**
+   * Constructs a new ProvisionRuleBuilder.
+   * @param parent
+   * @param name
+   * @internal
+   */
+  constructor(parent: Provisioner, name: string) {
+    this.parent = parent;
+    this.ruleName = name;
+  }
+
+  /**
+   * Sets the phase for the rule (by provisioner name, not ID).
+   * @param name - The phase name as registered with the provisioner.
+   * @returns This builder for chaining.
+   */
+  inPhase(name: string): this {
+    this.phaseName = name;
+    return this;
+  }
+
+  /**
+   * Sets the rule priority (lower number = higher priority).
+   * @param p - The priority value.
+   * @returns This builder for chaining.
+   */
+  priority(p: number): this {
+    this.rulePriority = p;
+    return this;
+  }
+
+  /**
+   * Sets the applicability expression.
+   * @param expr - The CEL expression for applicability.
+   * @returns This builder for chaining.
+   */
+  applicableWhen(expr: string): this {
+    this.applicable = expr;
+    return this;
+  }
+
+  /**
+   * Sets the matching expression.
+   * @param expr - The CEL expression for matching.
+   * @returns This builder for chaining.
+   */
+  when(expr: string): this {
+    this.expression = expr;
+    return this;
+  }
+
+  /**
+   * Sets the decision action and severity.
+   * @param action - The action string (e.g. "block").
+   * @param severity - The severity level.
+   * @returns This builder for chaining.
+   */
+  decide(action: string, severity: Severity): this {
+    this.ruleDecision = { action, severity };
+    return this;
+  }
+
+  /**
+   * Adds a score delta for the rule.
+   * @param delta - The score points to add.
+   * @returns This builder for chaining.
+   */
+  addScore(delta: number): this {
+    this.ruleScore = { add: delta };
+    return this;
+  }
+
+  /**
+   * Sets flow to halt.
+   * @returns This builder for chaining.
+   */
+  halt(): this {
+    this.ruleFlow = 'halt';
+    return this;
+  }
+
+  /**
+   * Sets flow to continue.
+   * @returns This builder for chaining.
+   */
+  continue(): this {
+    this.ruleFlow = 'continue';
+    return this;
+  }
+
+  /**
+   * Sets flow to skip_phase.
+   * @returns This builder for chaining.
+   */
+  skipPhase(): this {
+    this.ruleFlow = 'skip_phase';
+    return this;
+  }
+
+  /**
+   * Adds a list mutation to the rule.
+   * @param mutType - The mutation type (e.g. "list.add").
+   * @param listName - The list name.
+   * @param valuePath - The value path expression.
+   * @returns This builder for chaining.
+   */
+  mutateList(mutType: string, listName: string, valuePath: string): this {
+    this.ruleMutations.push({ mutationType: mutType, listName, valuePath });
+    return this;
+  }
+
+  /**
+   * Enables dry-run mode for the rule.
+   * @returns This builder for chaining.
+   */
+  dryRun(): this {
+    this.isDryRun = true;
+    return this;
+  }
+
+  /**
+   * Finishes building the rule and returns to the parent provisioner.
+   * @returns The parent Provisioner for chaining.
+   */
+  done(): Provisioner {
+    return this.parent._addRuleStep(this);
+  }
+
+  /**
+   * Constructs the SDK Actions from the builder state.
+   * @returns The Actions object for the API request.
+   * @internal
+   */
+  buildActions(): Actions {
+    const actions: {
+      decision?: Decision;
+      score?: ScoreOperation;
+      flow?: Flow;
+      mutations?: ListMutation[];
+    } = {};
+
+    if (this.ruleDecision) {
+      actions.decision = this.ruleDecision;
+    }
+    if (this.ruleScore) {
+      actions.score = this.ruleScore;
+    }
+    if (this.ruleFlow) {
+      actions.flow = this.ruleFlow;
+    }
+    if (this.ruleMutations.length > 0) {
+      actions.mutations = this.ruleMutations.map((m) => ({
+        type: m.mutationType,
+        target: m.listName,
+        value_path: m.valuePath,
+      }));
+    }
+
+    return actions;
+  }
+}

package/src/resources/apikeys.ts

@@ -0,0 +1,63 @@
+// ---------------------------------------------------------------------------
+// API Keys resource — CRUD
+// ---------------------------------------------------------------------------
+
+import type { HttpClient } from '../client/http.js';
+import type {
+  APIKey,
+  CreateAPIKeyRequest,
+  CreateAPIKeyResponse,
+  PaginatedResponse,
+  PaginationParams,
+  UpdateAPIKeyRequest,
+} from '../types.js';
+
+/**
+ * Resource for API key management.
+ */
+export class APIKeys {
+  private readonly http: HttpClient;
+
+  constructor(http: HttpClient) {
+    this.http = http;
+  }
+
+  /**
+   * Lists all API keys with cursor-based pagination.
+   * @param params - Optional pagination parameters.
+   * @returns A paginated list of API keys.
+   */
+  async list(params: PaginationParams = {}): Promise<PaginatedResponse<APIKey>> {
+    return this.http.get<PaginatedResponse<APIKey>>('/api/v1/api-keys', {
+      cursor: params.cursor,
+      limit: params.limit,
+    });
+  }
+
+  /**
+   * Creates a new API key. The plain key is returned only at creation time.
+   * @param request - The API key creation payload.
+   * @returns The created API key with the plain key value.
+   */
+  async create(request: CreateAPIKeyRequest): Promise<CreateAPIKeyResponse> {
+    return this.http.post<CreateAPIKeyResponse>('/api/v1/api-keys', request);
+  }
+
+  /**
+   * Updates an existing API key by ID.
+   * @param id - The API key ID.
+   * @param request - The update payload.
+   * @returns The updated API key.
+   */
+  async update(id: string, request: UpdateAPIKeyRequest): Promise<APIKey> {
+    return this.http.put<APIKey>(`/api/v1/api-keys/${id}`, request);
+  }
+
+  /**
+   * Deletes an API key by ID.
+   * @param id - The API key ID.
+   */
+  async delete(id: string): Promise<void> {
+    await this.http.delete<unknown>(`/api/v1/api-keys/${id}`);
+  }
+}

package/src/resources/audit.ts

@@ -0,0 +1,29 @@
+// ---------------------------------------------------------------------------
+// Audit resource — list
+// ---------------------------------------------------------------------------
+
+import type { HttpClient } from '../client/http.js';
+import type { EvaluationLog, PaginatedResponse, PaginationParams } from '../types.js';
+
+/**
+ * Resource for audit log access.
+ */
+export class Audit {
+  private readonly http: HttpClient;
+
+  constructor(http: HttpClient) {
+    this.http = http;
+  }
+
+  /**
+   * Lists audit logs with cursor-based pagination.
+   * @param params - Optional pagination parameters.
+   * @returns A paginated list of audit entries.
+   */
+  async list(params: PaginationParams = {}): Promise<PaginatedResponse<EvaluationLog>> {
+    return this.http.get<PaginatedResponse<EvaluationLog>>('/api/v1/audit', {
+      cursor: params.cursor,
+      limit: params.limit,
+    });
+  }
+}

package/src/resources/evaluations.ts

@@ -0,0 +1,38 @@
+// ---------------------------------------------------------------------------
+// Evaluations resource — list, get
+// ---------------------------------------------------------------------------
+
+import type { HttpClient } from '../client/http.js';
+import type { EvaluationLog, PaginatedResponse, PaginationParams } from '../types.js';
+
+/**
+ * Resource for evaluation log inspection.
+ */
+export class Evaluations {
+  private readonly http: HttpClient;
+
+  constructor(http: HttpClient) {
+    this.http = http;
+  }
+
+  /**
+   * Lists evaluation logs with cursor-based pagination.
+   * @param params - Optional pagination parameters.
+   * @returns A paginated list of evaluation logs.
+   */
+  async list(params: PaginationParams = {}): Promise<PaginatedResponse<EvaluationLog>> {
+    return this.http.get<PaginatedResponse<EvaluationLog>>('/api/v1/evaluations', {
+      cursor: params.cursor,
+      limit: params.limit,
+    });
+  }
+
+  /**
+   * Retrieves a single evaluation log by ID.
+   * @param id - The evaluation log ID.
+   * @returns The evaluation log with full pipeline trace.
+   */
+  async get(id: string): Promise<EvaluationLog> {
+    return this.http.get<EvaluationLog>(`/api/v1/evaluations/${id}`);
+  }
+}

package/src/resources/events.ts

@@ -0,0 +1,61 @@
+// ---------------------------------------------------------------------------
+// Events resource — ingest, ingestAsync, ingestOnly, simulate
+// ---------------------------------------------------------------------------
+
+import type { HttpClient } from '../client/http.js';
+import type { IngestRequest, IngestResult, SuccessResponse } from '../types.js';
+
+/**
+ * Resource for event ingestion operations.
+ */
+export class Events {
+  private readonly http: HttpClient;
+
+  constructor(http: HttpClient) {
+    this.http = http;
+  }
+
+  /**
+   * Ingests an event synchronously and returns the decision.
+   * @param request - The ingest request payload.
+   * @returns The ingestion result with decision and score.
+   */
+  async ingest(request: IngestRequest): Promise<IngestResult> {
+    return this.http.post<IngestResult>('/api/v1/events/ingest', request);
+  }
+
+  /**
+   * Ingests an event asynchronously (fire-and-forget with acknowledgement).
+   * @param request - The ingest request payload.
+   * @returns The event ID assigned by the server.
+   */
+  async ingestAsync(request: IngestRequest): Promise<string> {
+    const result = await this.http.post<SuccessResponse<{ event_id: string }>>(
+      '/api/v1/events/ingest-async',
+      request,
+    );
+    return result.data.event_id;
+  }
+
+  /**
+   * Ingests an event for storage only, without evaluation.
+   * @param request - The ingest request payload.
+   * @returns The event ID assigned by the server.
+   */
+  async ingestOnly(request: IngestRequest): Promise<string> {
+    const result = await this.http.post<SuccessResponse<{ event_id: string }>>(
+      '/api/v1/events/ingest-only',
+      request,
+    );
+    return result.data.event_id;
+  }
+
+  /**
+   * Simulates event evaluation without persisting (dry-run).
+   * @param request - The ingest request payload.
+   * @returns The simulated result with decision and trace.
+   */
+  async simulate(request: IngestRequest): Promise<IngestResult> {
+    return this.http.post<IngestResult>('/api/v1/events/simulate', request);
+  }
+}