Errors API Reference

Error
└── MacpSdkError                    Base class for all SDK errors
    ├── MacpTransportError          gRPC connectivity issues
    │   ├── MacpTimeoutError        RPC deadline exceeded
    │   └── MacpRetryError          Retries exhausted
    ├── MacpAckError                Runtime rejected the message
    ├── MacpSessionError             Session-state mismatch
    └── MacpIdentityMismatchError   Explicit sender conflicts with auth.expectedSender

import { MacpSdkError } from 'macp-sdk-typescript';

const err = new MacpSdkError('something went wrong');
err.name;    // 'MacpSdkError'
err.message; // 'something went wrong'
err instanceof Error;        // true
err instanceof MacpSdkError; // true

import { MacpTransportError } from 'macp-sdk-typescript';

try {
  await client.initialize();
} catch (err) {
  if (err instanceof MacpTransportError) {
    // gRPC layer error
    console.log(err.message); // e.g., 'Connection refused'
    console.log(err.code);    // e.g., 'UNAVAILABLE'
  }
}

import { MacpAckError } from 'macp-sdk-typescript';

try {
  await session.vote({ proposalId: 'p1', vote: 'approve' });
} catch (err) {
  if (err instanceof MacpAckError) {
    err.name;              // 'MacpAckError'
    err.message;           // 'SESSION_NOT_OPEN: session already resolved'
    err.ack;               // full Ack object
    err.ack.ok;            // false
    err.ack.error?.code;   // 'SESSION_NOT_OPEN'
    err.ack.error?.message;// 'session already resolved'
    err.ack.sessionState;  // 'SESSION_STATE_RESOLVED'
    err.failure;           // structured AckFailure record (see below)
    err.grpcMetadata;      // optional gRPC trailing metadata
  }
}

interface AckFailure {
  code: string;       // ack.error.code, or 'UNKNOWN'
  message: string;    // ack.error.message, or 'runtime returned nack'
  sessionId: string;
  messageId: string;
  reasons: string[];  // parsed from ack.error.details JSON, falling back to
                      // the 'macp-error-details-bin' gRPC trailing metadata
}

const ack = await client.send(envelope, { raiseOnNack: false });
if (!ack.ok) {
  // handle rejection without exception
}

import { Auth, MacpIdentityMismatchError } from 'macp-sdk-typescript';

const session = new DecisionSession(client, {
  auth: Auth.bearer('alice-token', { expectedSender: 'alice' }),
});

try {
  await session.propose({ proposalId: 'p1', option: 'x', sender: 'mallory' });
} catch (err) {
  if (err instanceof MacpIdentityMismatchError) {
    err.expectedSender; // 'alice'
    err.actualSender;   // 'mallory'
  }
}