@emilia-protocol/sdk 0.9.0 → 0.10.0

package/src/index.ts

@@ -3,7 +3,7 @@
 // -- Params -----------------------------------------------------------------
 
 export interface EPClientOptions {
-  baseUrl: string;
+  baseUrl?: string;
   apiKey?: string;
   timeout?: number;
   retries?: number;
@@ -119,6 +119,155 @@ export interface CreateSuppressionParams {
   expires_at: string;
 }
 
+// -- v1 Guard Params --------------------------------------------------------
+
+export type GuardActionType =
+  | 'benefit_bank_account_change'
+  | 'benefit_address_change'
+  | 'caseworker_override'
+  | 'vendor_bank_account_change'
+  | 'beneficiary_creation'
+  | 'large_payment_release'
+  | 'ai_agent_payment_action';
+
+export type GuardDecision = 'allow' | 'observe' | 'allow_with_signoff' | 'deny';
+export type GuardEnforcementMode = 'observe' | 'warn' | 'enforce';
+
+export interface GuardQuorumPolicy {
+  mode?: 'threshold' | 'all';
+  required: number;
+  approvers: Array<{ role: string; approver: string }>;
+}
+
+export interface CreateTrustReceiptParams {
+  organizationId?: string;
+  actionType: GuardActionType | string;
+  targetResourceId: string;
+  policyId?: string;
+  enforcementMode?: GuardEnforcementMode;
+  beforeState?: Record<string, unknown>;
+  afterState?: Record<string, unknown>;
+  targetChangedFields?: string[];
+  amount?: number;
+  currency?: string;
+  riskFlags?: string[];
+  actorRole?: string;
+  actorDepartment?: string;
+  businessHours?: boolean;
+  velocitySameActor24h?: number;
+  priorDenialsActor30d?: number;
+  priorChangesTarget30d?: number;
+  destinationAgeDays?: number;
+  quorumPolicy?: GuardQuorumPolicy;
+  metadata?: Record<string, unknown>;
+}
+
+export interface TrustReceipt {
+  receipt_id: string;
+  decision: GuardDecision;
+  observed_decision?: GuardDecision | null;
+  policy_id: string;
+  policy_hash: string;
+  action_hash: string;
+  before_state_hash?: string | null;
+  after_state_hash?: string | null;
+  nonce: string;
+  expires_at: string;
+  signoff_required: boolean;
+  signoff_request_id?: string | null;
+  risk_flags?: string[];
+  receipt_status: string;
+  enforcement_mode: string;
+  reasons?: string[];
+  canonical_action: Record<string, unknown>;
+}
+
+export interface TrustReceiptState {
+  receipt_id: string;
+  organization_id: string;
+  action_type: string;
+  decision: GuardDecision;
+  enforcement_mode: string;
+  policy_id: string;
+  policy_hash: string;
+  action_hash: string;
+  expires_at: string;
+  signoff_required: boolean;
+  receipt_status: string;
+  signoff_key_class?: string | null;
+  timeline_event_count: number;
+}
+
+export interface RequestSignoffParams {
+  receiptId: string;
+  approverId?: string;
+  expiresInMinutes?: number;
+  comment?: string;
+}
+
+export interface SignoffRequest {
+  signoff_id?: string;
+  receipt_id: string;
+  action_hash: string;
+  initiator_id: string;
+  approver_id?: string;
+  expires_at: string;
+  status: string;
+  quorum?: { mode: string; required: number; count: number };
+  signoffs?: Array<{ signoff_id: string; role?: string; approver_id: string }>;
+}
+
+export interface ConsumeTrustReceiptResult {
+  receipt_id: string;
+  status: string;
+  consumed_at: string;
+  consumed_by_system: string;
+  execution_reference_id?: string | null;
+}
+
+export interface ExecutionAttestation {
+  receipt_id: string;
+  status: string;
+  binding_status: string;
+  executed_action_hash: string;
+  approved_action_hash: string;
+  execution_integrity: Record<string, unknown>;
+}
+
+export interface TrustReceiptEvidence {
+  document: Record<string, unknown> | null;
+  public_key: string | null;
+  signed: boolean;
+  verify_with: string;
+  receipt_id: string;
+  organization_id: string;
+  issued_at: string;
+  expires_at: string;
+  schema_version: string;
+  [key: string]: unknown;
+}
+
+export interface RequireReceiptParams extends CreateTrustReceiptParams {
+  executingSystem: string;
+  executionReferenceId?: string;
+  approverId?: string;
+  signoffComment?: string;
+  signoffExpiresInMinutes?: number;
+  onSignoffRequired?: (ctx: { client: EPClient; receipt: TrustReceipt; signoff?: SignoffRequest }) => Promise<void | boolean | { approved?: boolean }>;
+  executedAction?: Record<string, unknown> | ((ctx: { receipt: TrustReceipt; result: unknown }) => Record<string, unknown>);
+  executionId?: string | ((result: unknown) => string | undefined);
+  fetchEvidence?: boolean;
+}
+
+export interface RequireReceiptResult<T> {
+  result: T;
+  receipt: TrustReceipt;
+  signoff?: SignoffRequest;
+  consume: ConsumeTrustReceiptResult;
+  execution: ExecutionAttestation;
+  evidence?: TrustReceiptEvidence;
+}
+
 // -- Eye Responses ----------------------------------------------------------
 
 export interface ObservationResponse {
@@ -198,14 +347,21 @@ export interface SimulatePolicyParams {
 
 export interface RolloutPolicyParams {
   policyId: string;
-  strategy: 'canary' | 'blue-green' | 'linear' | string;
-  percentage?: number;
+  /** Policy version number to roll out (resolved against handshake_policies). */
+  version: number;
+  /** Target environment, e.g. "production" or "staging". */
+  environment: string;
+  strategy?: 'immediate' | 'canary';
+  /** Traffic percentage (1–99) for canary rollouts. */
+  canaryPct?: number;
 }
 
 export interface DiffPolicyVersionsParams {
   policyId: string;
-  versionA: string;
-  versionB: string;
+  /** First version number to compare. */
+  v1: number;
+  /** Second version number to compare. */
+  v2: number;
 }
 
 // -- Responses --------------------------------------------------------------
@@ -463,34 +619,72 @@ export interface PolicySimulationResult {
 }
 
 export interface PolicyRolloutResult {
-  policyId: string;
+  rollout_id: string;
+  /** handshake_policies policy_id of the rolled-out version row. */
+  policy_id: string;
+  policy_key: string;
+  version: number;
+  environment: string;
   strategy: string;
-  percentage: number;
   status: string;
-  startedAt: string;
+  canary_pct: number | null;
+  initiated_at: string;
+  tenant_id: string;
 }
 
+/**
+ * A policy version is a handshake_policies row. Versions sharing a policy_key
+ * form the version history of a single policy.
+ */
 export interface PolicyVersion {
-  versionId: string;
-  policyId: string;
+  policy_id: string;
+  policy_key: string;
   version: number;
-  createdAt: string;
-  createdBy: string;
-  changelog?: string;
+  name: string;
+  mode: string;
+  status: string;
+  rules: Record<string, unknown>;
+  created_at: string;
+  updated_at: string;
 }
 
-export interface PolicyDiff {
-  policyId: string;
-  versionA: string;
-  versionB: string;
-  changes: PolicyChange[];
+export interface PolicyVersionsResult {
+  policy_id: string;
+  policy_key: string;
+  versions: PolicyVersion[];
+  count: number;
+  tenant_id: string;
 }
 
+/** A single classified field change between two policy versions' rules. */
 export interface PolicyChange {
-  field: string;
-  oldValue: unknown;
-  newValue: unknown;
-  type: 'added' | 'removed' | 'modified';
+  path: string;
+  before: unknown;
+  after: unknown;
+  risk: 'loosening' | 'tightening' | 'neutral';
+  rationale: string;
+}
+
+/** Semantic diff of v1.rules vs v2.rules. */
+export interface PolicyRulesDiff {
+  changes: PolicyChange[];
+  risk: 'loosening' | 'tightening' | 'neutral';
+  summary: {
+    loosening: number;
+    tightening: number;
+    neutral: number;
+  };
+}
+
+export interface PolicyDiff {
+  policy_id: string;
+  policy_key: string;
+  /** The lower-numbered handshake_policies version row. */
+  v1: PolicyVersion;
+  /** The higher-numbered handshake_policies version row. */
+  v2: PolicyVersion;
+  diff: PolicyRulesDiff;
+  tenant_id: string;
 }
 
 // -- Error ------------------------------------------------------------------
@@ -594,25 +788,43 @@ export class EPCloudClient {
     }, true);
   }
 
-  /** Begin a rollout of a policy using the specified strategy. */
-  async rolloutPolicy(policyId: string, strategy: string, percentage?: number): Promise<PolicyRolloutResult> {
+  /**
+   * Roll out a specific policy version to an environment. The version is
+   * resolved against handshake_policies by the policy's policy_key. Immediate
+   * rollouts supersede the prior active rollout for that (policy_key,
+   * environment); canary rollouts coexist (canaryPct in 1–99).
+   */
+  async rolloutPolicy(
+    policyId: string,
+    version: number,
+    environment: string,
+    strategy: 'immediate' | 'canary' = 'immediate',
+    canaryPct?: number,
+  ): Promise<PolicyRolloutResult> {
     return this._request<PolicyRolloutResult>('POST', `/api/cloud/policies/${encodeURIComponent(policyId)}/rollout`, {
+      version,
+      environment,
       strategy,
-      percentage,
+      ...(strategy === 'canary' && canaryPct !== undefined ? { canary_pct: canaryPct } : {}),
     }, true);
   }
 
-  /** List all versions of a policy. */
-  async getPolicyVersions(policyId: string): Promise<PolicyVersion[]> {
-    return this._request<PolicyVersion[]>('GET', `/api/cloud/policies/${encodeURIComponent(policyId)}/versions`, undefined, true);
+  /**
+   * List all versions of a policy. Versions are the handshake_policies rows
+   * sharing the policy's policy_key, returned newest-first inside an envelope.
+   */
+  async getPolicyVersions(policyId: string): Promise<PolicyVersionsResult> {
+    return this._request<PolicyVersionsResult>('GET', `/api/cloud/policies/${encodeURIComponent(policyId)}/versions`, undefined, true);
   }
 
-  /** Diff two versions of a policy to see what changed. */
-  async diffPolicyVersions(policyId: string, versionA: string, versionB: string): Promise<PolicyDiff> {
-    return this._request<PolicyDiff>('POST', `/api/cloud/policies/${encodeURIComponent(policyId)}/diff`, {
-      versionA,
-      versionB,
-    }, true);
+  /**
+   * Diff two versions of a policy to see what changed between their rules.
+   * v1 and v2 are version numbers; the response includes both version rows and
+   * a semantic diff classified as loosening / tightening / neutral.
+   */
+  async diffPolicyVersions(policyId: string, v1: number, v2: number): Promise<PolicyDiff> {
+    const qs = this._toQs({ v1: String(v1), v2: String(v2) });
+    return this._request<PolicyDiff>('GET', `/api/cloud/policies/${encodeURIComponent(policyId)}/diff${qs}`, undefined, true);
   }
 
   /** @internal Build query string from SignoffFilters. */
@@ -646,6 +858,31 @@ export class EPCloudClient {
 
 // -- Client -----------------------------------------------------------------
 
+function trustReceiptBody(params: CreateTrustReceiptParams): Record<string, unknown> {
+  return {
+    organization_id: params.organizationId,
+    action_type: params.actionType,
+    target_resource_id: params.targetResourceId,
+    policy_id: params.policyId,
+    enforcement_mode: params.enforcementMode,
+    before_state: params.beforeState,
+    after_state: params.afterState,
+    target_changed_fields: params.targetChangedFields,
+    amount: params.amount,
+    currency: params.currency,
+    risk_flags: params.riskFlags,
+    actor_role: params.actorRole,
+    actor_department: params.actorDepartment,
+    business_hours: params.businessHours,
+    velocity_same_actor_24h: params.velocitySameActor24h,
+    prior_denials_actor_30d: params.priorDenialsActor30d,
+    prior_changes_target_30d: params.priorChangesTarget30d,
+    destination_age_days: params.destinationAgeDays,
+    quorum_policy: params.quorumPolicy,
+    metadata: params.metadata,
+  };
+}
+
 export class EPClient {
   private readonly baseUrl: string;
   private readonly apiKey: string;
@@ -655,9 +892,15 @@ export class EPClient {
   /** Cloud-specific endpoints (dashboards, analytics, audit, policy management). */
   public readonly cloud: EPCloudClient;
 
-  constructor(options: EPClientOptions) {
-    this.baseUrl = options.baseUrl.replace(/\/+$/, '');
-    this.apiKey = options.apiKey ?? '';
+  constructor(options: EPClientOptions = {}) {
+    const env = typeof process !== 'undefined' && process.env ? process.env : {};
+    // Trim trailing slashes without a regex — avoids the polynomial-backtracking
+    // CodeQL flags on /\/+$/ for long all-slash inputs.
+    const rawBase = options.baseUrl ?? env.EP_BASE_URL ?? 'https://emiliaprotocol.ai';
+    let baseEnd = rawBase.length;
+    while (baseEnd > 0 && rawBase.charCodeAt(baseEnd - 1) === 47 /* '/' */) baseEnd--;
+    this.baseUrl = rawBase.slice(0, baseEnd);
+    this.apiKey = options.apiKey ?? env.EP_API_KEY ?? '';
     this.timeout = options.timeout ?? 10_000;
     this.retries = options.retries ?? 2;
 
@@ -674,7 +917,7 @@ export class EPClient {
     const url = `${this.baseUrl}${path}`;
     const headers: Record<string, string> = {
       'Content-Type': 'application/json',
-      'User-Agent': '@emilia-protocol/sdk/0.9.0',
+      'User-Agent': '@emilia-protocol/sdk/0.10.0',
     };
     if (auth && this.apiKey) {
       headers['Authorization'] = `Bearer ${this.apiKey}`;
@@ -694,8 +937,18 @@ export class EPClient {
         const data: unknown = await res.json().catch(() => undefined);
         if (!res.ok) {
           const p = data as Record<string, unknown> | undefined;
-          const msg = typeof p?.['error'] === 'string' ? p['error'] : `EP API error: ${res.status}`;
-          const code = typeof p?.['code'] === 'string' ? p['code'] : undefined;
+          const msg = typeof p?.['error'] === 'string'
+            ? p['error']
+            : typeof p?.['detail'] === 'string'
+              ? p['detail']
+              : typeof p?.['title'] === 'string'
+                ? p['title']
+                : `EP API error: ${res.status}`;
+          const code = typeof p?.['code'] === 'string'
+            ? p['code']
+            : typeof p?.['type'] === 'string'
+              ? p['type'].split('/').pop()
+              : undefined;
           throw new EPError(msg, res.status, code);
         }
         return data as T;
@@ -798,6 +1051,153 @@ export class EPClient {
     );
   }
 
+  // ------------------------------------------------------------------
+  // v1 Trust Receipt Enforcement
+  // ------------------------------------------------------------------
+
+  /** Create a v1 pre-action trust receipt for a high-risk mutation. */
+  async createTrustReceipt(params: CreateTrustReceiptParams): Promise<TrustReceipt> {
+    return this.request<TrustReceipt>('POST', '/api/v1/trust-receipts', trustReceiptBody(params), true);
+  }
+
+  /** Read current receipt state from the append-only v1 audit timeline. */
+  async getTrustReceipt(receiptId: string): Promise<TrustReceiptState> {
+    return this.request<TrustReceiptState>(
+      'GET',
+      `/api/v1/trust-receipts/${encodeURIComponent(receiptId)}`,
+      undefined,
+      true,
+    );
+  }
+
+  /** Request human signoff for a receipt that requires approval. */
+  async requestSignoff(params: RequestSignoffParams): Promise<SignoffRequest> {
+    return this.request<SignoffRequest>('POST', '/api/v1/signoffs/request', {
+      receipt_id: params.receiptId,
+      approver_id: params.approverId,
+      expires_in_minutes: params.expiresInMinutes,
+      comment: params.comment,
+    }, true);
+  }
+
+  /** Consume a receipt before mutation. If this fails, do not execute the write. */
+  async consumeTrustReceipt(
+    receiptId: string,
+    params: { actionHash: string; executingSystem: string; executionReferenceId?: string },
+  ): Promise<ConsumeTrustReceiptResult> {
+    return this.request<ConsumeTrustReceiptResult>(
+      'POST',
+      `/api/v1/trust-receipts/${encodeURIComponent(receiptId)}/consume`,
+      {
+        action_hash: params.actionHash,
+        executing_system: params.executingSystem,
+        execution_reference_id: params.executionReferenceId,
+      },
+      true,
+    );
+  }
+
+  /** Emit the post-mutation execution attestation bound to the consumed receipt. */
+  async attestExecution(
+    receiptId: string,
+    params: {
+      executedAction: Record<string, unknown>;
+      executingSystem: string;
+      executionId?: string;
+      executedAt?: string;
+    },
+  ): Promise<ExecutionAttestation> {
+    return this.request<ExecutionAttestation>(
+      'POST',
+      `/api/v1/trust-receipts/${encodeURIComponent(receiptId)}/execution`,
+      {
+        executed_action: params.executedAction,
+        executing_system: params.executingSystem,
+        execution_id: params.executionId,
+        executed_at: params.executedAt,
+      },
+      true,
+    );
+  }
+
+  /** Fetch the signed evidence packet, when the receipt is in a signable state. */
+  async getTrustReceiptEvidence(receiptId: string): Promise<TrustReceiptEvidence> {
+    return this.request<TrustReceiptEvidence>(
+      'GET',
+      `/api/v1/trust-receipts/${encodeURIComponent(receiptId)}/evidence`,
+      undefined,
+      true,
+    );
+  }
+
+  /**
+   * Wrap a dangerous mutation in the v1 receipt lifecycle.
+   * The mutation runs only after create + consume succeed.
+   */
+  async requireReceipt<T>(
+    params: RequireReceiptParams,
+    mutate: (ctx: { receipt: TrustReceipt; consume: ConsumeTrustReceiptResult }) => Promise<T>,
+  ): Promise<RequireReceiptResult<T>> {
+    const receipt = await this.createTrustReceipt(params);
+    if (receipt.decision === 'deny' || receipt.receipt_status === 'denied') {
+      throw new EPError('EMILIA denied the action before execution', 403, 'receipt_denied');
+    }
+
+    let signoff: SignoffRequest | undefined;
+    if (receipt.signoff_required) {
+      if (!params.approverId && !params.quorumPolicy) {
+        throw new EPError('Receipt requires signoff; pass approverId or quorumPolicy', 409, 'missing_approver_id');
+      }
+      signoff = await this.requestSignoff({
+        receiptId: receipt.receipt_id,
+        approverId: params.approverId,
+        expiresInMinutes: params.signoffExpiresInMinutes,
+        comment: params.signoffComment,
+      });
+      if (!params.onSignoffRequired) {
+        throw new EPError('Receipt requires human signoff before the mutation can run', 409, 'signoff_required');
+      }
+      const signoffResult = await params.onSignoffRequired({ client: this, receipt, signoff });
+      if (signoffResult === false || (typeof signoffResult === 'object' && signoffResult?.approved === false)) {
+        throw new EPError('Human signoff was not approved', 403, 'signoff_rejected');
+      }
+    }
+
+    const consume = await this.consumeTrustReceipt(receipt.receipt_id, {
+      actionHash: receipt.action_hash,
+      executingSystem: params.executingSystem,
+      executionReferenceId: params.executionReferenceId,
+    });
+    const result = await mutate({ receipt, consume });
+    const executedAction = typeof params.executedAction === 'function'
+      ? params.executedAction({ receipt, result })
+      : params.executedAction ?? receipt.canonical_action;
+    const executionId = typeof params.executionId === 'function'
+      ? params.executionId(result)
+      : params.executionId;
+    const execution = await this.attestExecution(receipt.receipt_id, {
+      executedAction,
+      executingSystem: params.executingSystem,
+      executionId,
+    });
+    const evidence = params.fetchEvidence
+      ? await this.getTrustReceiptEvidence(receipt.receipt_id)
+      : undefined;
+
+    return { result, receipt, signoff, consume, execution, evidence };
+  }
+
+  /** Wrap an existing async function with requireReceipt(). */
+  withReceipt<TArgs extends unknown[], TResult>(
+    params: RequireReceiptParams | ((...args: TArgs) => RequireReceiptParams),
+    mutate: (...args: TArgs) => Promise<TResult>,
+  ): (...args: TArgs) => Promise<RequireReceiptResult<TResult>> {
+    return async (...args: TArgs) => {
+      const resolved = typeof params === 'function' ? params(...args) : params;
+      return this.requireReceipt(resolved, () => mutate(...args));
+    };
+  }
+
   // ------------------------------------------------------------------
   // Signoff extension
   // ------------------------------------------------------------------