crypto-aio 0.2.0 → 1.0.0-rc.1

package/dist/core/errors/error.js

@@ -5,12 +5,21 @@ exports.createError = createError;
 exports.isCryptoAioError = isCryptoAioError;
 exports.withContext = withContext;
 const codes_1 = require("./codes");
+/**
+ * Every failure the library reports. Match on `code` and `category`, and on the `details`
+ * and `context` fields the Errors reference lists; message texts are not covered by
+ * semver.
+ */
 class CryptoAioError extends Error {
     code;
     category;
+    /** Whether the same call may succeed if made again. */
     retryable;
+    /** Whether the call may have reached the chain, so its effect is unknown. */
     ambiguous;
+    /** Redacted ids of where it happened, such as `operationId`. */
     context;
+    /** Code-specific facts, such as `required` and `available` for `INSUFFICIENT_FUNDS`. */
     details;
     constructor(code, message, options = {}) {
         super(message, options.cause === undefined ? undefined : { cause: options.cause });
@@ -24,6 +33,7 @@ class CryptoAioError extends Error {
         if (options.details)
             this.details = Object.freeze({ ...options.details });
     }
+    /** The error as plain data, without its stack or cause. */
     toJSON() {
         return {
             name: this.name,
@@ -38,48 +48,56 @@ class CryptoAioError extends Error {
     }
 }
 exports.CryptoAioError = CryptoAioError;
+/** A configuration that cannot work: an invalid option, a missing SDK package, an incompatible selection. */
 class ConfigError extends CryptoAioError {
     constructor(code, message, options) {
         super(code, message, options);
     }
 }
 exports.ConfigError = ConfigError;
+/** An operation the selected chain, network or library does not support. */
 class UnsupportedCapabilityError extends CryptoAioError {
     constructor(code, message, options) {
         super(code, message, options);
     }
 }
 exports.UnsupportedCapabilityError = UnsupportedCapabilityError;
+/** An input that is not valid: an address, an amount, an asset or an intent. */
 class ValidationError extends CryptoAioError {
     constructor(code, message, options) {
         super(code, message, options);
     }
 }
 exports.ValidationError = ValidationError;
+/** A failure of the endpoints: unavailable, rate-limited, misconfigured, inconsistent, or a definitive refusal. */
 class ProviderError extends CryptoAioError {
     constructor(code, message, options) {
         super(code, message, options);
     }
 }
 exports.ProviderError = ProviderError;
+/** An answer of the chain about a transaction: funds, nonce, fee, refusal, revert, expiry, replacement. */
 class ChainError extends CryptoAioError {
     constructor(code, message, options) {
         super(code, message, options);
     }
 }
 exports.ChainError = ChainError;
+/** A failure to sign: no signer, a failed or mismatched signature, a policy veto, a key that cannot be exported. */
 class SigningError extends CryptoAioError {
     constructor(code, message, options) {
         super(code, message, options);
     }
 }
 exports.SigningError = SigningError;
+/** A conflict with stored state: idempotency, fencing, versions, transitions, leases, record formats. */
 class StateError extends CryptoAioError {
     constructor(code, message, options) {
         super(code, message, options);
     }
 }
 exports.StateError = StateError;
+/** A call that ran out of time. */
 class TimeoutError extends CryptoAioError {
     constructor(code, message, options) {
         super(code, message, options);
@@ -96,10 +114,12 @@ const BY_CATEGORY = {
     state: StateError,
     timeout: TimeoutError,
 };
+/** An error of `code`'s class. */
 function createError(code, message, options) {
     const Ctor = BY_CATEGORY[codes_1.ERROR_CODES[code].category];
     return new Ctor(code, message, options);
 }
+/** Whether `value` is a `CryptoAioError`, of `code` when given. */
 function isCryptoAioError(value, code) {
     return value instanceof CryptoAioError && (code === undefined || value.code === code);
 }

package/dist/core/errors/error.js.map

@@ -1 +1 @@
-{"version":3,"file":"error.js","sourceRoot":"","sources":["../../../src/core/errors/error.ts"],"names":[],"mappings":"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","sourcesContent":["import { ERROR_CODES, type CodesOf, type ErrorCategory, type ErrorCode } from './codes';\n\nexport type { CodesOf, ErrorCategory, ErrorCode } from './codes';\n\nexport type ErrorContextValue = string | number | boolean | undefined;\nexport type ErrorContext = Readonly<Record<string, ErrorContextValue>>;\n\nexport interface CryptoAioErrorOptions {\n  readonly cause?: unknown;\n  readonly context?: ErrorContext;\n  readonly details?: Readonly<Record<string, unknown>>;\n  readonly retryable?: boolean;\n  readonly ambiguous?: boolean;\n}\n\nexport interface SerializedError {\n  readonly name: string;\n  readonly code: ErrorCode;\n  readonly category: ErrorCategory;\n  readonly message: string;\n  readonly retryable: boolean;\n  readonly ambiguous: boolean;\n  readonly context: ErrorContext;\n  readonly details?: Readonly<Record<string, unknown>>;\n}\n\nexport class CryptoAioError extends Error {\n  readonly code: ErrorCode;\n  readonly category: ErrorCategory;\n  readonly retryable: boolean;\n  readonly ambiguous: boolean;\n  readonly context: ErrorContext;\n  readonly details?: Readonly<Record<string, unknown>>;\n\n  constructor(code: ErrorCode, message: string, options: CryptoAioErrorOptions = {}) {\n    super(message, options.cause === undefined ? undefined : { cause: options.cause });\n    this.name = new.target.name;\n    const definition = ERROR_CODES[code];\n    this.code = code;\n    this.category = definition.category;\n    this.retryable = options.retryable ?? definition.retryable;\n    this.ambiguous = options.ambiguous ?? false;\n    this.context = Object.freeze({ ...options.context });\n    if (options.details) this.details = Object.freeze({ ...options.details });\n  }\n\n  toJSON(): SerializedError {\n    return {\n      name: this.name,\n      code: this.code,\n      category: this.category,\n      message: this.message,\n      retryable: this.retryable,\n      ambiguous: this.ambiguous,\n      context: this.context,\n      ...(this.details ? { details: this.details } : {}),\n    };\n  }\n}\n\nexport class ConfigError extends CryptoAioError {\n  constructor(code: CodesOf<'config'>, message: string, options?: CryptoAioErrorOptions) {\n    super(code, message, options);\n  }\n}\nexport class UnsupportedCapabilityError extends CryptoAioError {\n  constructor(\n    code: CodesOf<'unsupported'>,\n    message: string,\n    options?: CryptoAioErrorOptions,\n  ) {\n    super(code, message, options);\n  }\n}\nexport class ValidationError extends CryptoAioError {\n  constructor(\n    code: CodesOf<'validation'>,\n    message: string,\n    options?: CryptoAioErrorOptions,\n  ) {\n    super(code, message, options);\n  }\n}\nexport class ProviderError extends CryptoAioError {\n  constructor(\n    code: CodesOf<'provider'>,\n    message: string,\n    options?: CryptoAioErrorOptions,\n  ) {\n    super(code, message, options);\n  }\n}\nexport class ChainError extends CryptoAioError {\n  constructor(code: CodesOf<'chain'>, message: string, options?: CryptoAioErrorOptions) {\n    super(code, message, options);\n  }\n}\nexport class SigningError extends CryptoAioError {\n  constructor(\n    code: CodesOf<'signing'>,\n    message: string,\n    options?: CryptoAioErrorOptions,\n  ) {\n    super(code, message, options);\n  }\n}\nexport class StateError extends CryptoAioError {\n  constructor(code: CodesOf<'state'>, message: string, options?: CryptoAioErrorOptions) {\n    super(code, message, options);\n  }\n}\nexport class TimeoutError extends CryptoAioError {\n  constructor(\n    code: CodesOf<'timeout'>,\n    message: string,\n    options?: CryptoAioErrorOptions,\n  ) {\n    super(code, message, options);\n  }\n}\n\ntype AnyErrorConstructor = new (\n  code: ErrorCode,\n  message: string,\n  options?: CryptoAioErrorOptions,\n) => CryptoAioError;\n\nconst BY_CATEGORY: Record<ErrorCategory, AnyErrorConstructor> = {\n  config: ConfigError as AnyErrorConstructor,\n  unsupported: UnsupportedCapabilityError as AnyErrorConstructor,\n  validation: ValidationError as AnyErrorConstructor,\n  provider: ProviderError as AnyErrorConstructor,\n  chain: ChainError as AnyErrorConstructor,\n  signing: SigningError as AnyErrorConstructor,\n  state: StateError as AnyErrorConstructor,\n  timeout: TimeoutError as AnyErrorConstructor,\n};\n\nexport function createError(\n  code: ErrorCode,\n  message: string,\n  options?: CryptoAioErrorOptions,\n): CryptoAioError {\n  const Ctor = BY_CATEGORY[ERROR_CODES[code].category];\n  return new Ctor(code, message, options);\n}\n\nexport function isCryptoAioError(\n  value: unknown,\n  code?: ErrorCode,\n): value is CryptoAioError {\n  return value instanceof CryptoAioError && (code === undefined || value.code === code);\n}\n\n/**\n * Returns a copy of `error` (same class, same stack) with merged context, and optional flag\n * and `details` overrides. The copy keeps the stack of the error it reports.\n */\nexport function withContext(\n  error: CryptoAioError,\n  context: ErrorContext,\n  overrides: {\n    readonly ambiguous?: boolean;\n    readonly retryable?: boolean;\n    readonly details?: Readonly<Record<string, unknown>>;\n  } = {},\n): CryptoAioError {\n  const Ctor = error.constructor as AnyErrorConstructor;\n  const details = overrides.details ?? error.details;\n  const copy = new Ctor(error.code, error.message, {\n    cause: error.cause,\n    context: { ...error.context, ...context },\n    ...(details ? { details } : {}),\n    retryable: overrides.retryable ?? error.retryable,\n    ambiguous: overrides.ambiguous ?? error.ambiguous,\n  });\n  if (error.stack !== undefined) {\n    Object.defineProperty(copy, 'stack', {\n      value: error.stack,\n      writable: true,\n      configurable: true,\n    });\n  }\n  return copy;\n}\n"]}
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../../../src/core/errors/error.ts"],"names":[],"mappings":"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","sourcesContent":["import { ERROR_CODES, type CodesOf, type ErrorCategory, type ErrorCode } from './codes';\n\nexport type { CodesOf, ErrorCategory, ErrorCode } from './codes';\n\n/** One value of an error's `context`. */\nexport type ErrorContextValue = string | number | boolean | undefined;\n/** Redacted identifiers of where an error happened, such as `operationId` or `endpointId`. */\nexport type ErrorContext = Readonly<Record<string, ErrorContextValue>>;\n\n/** What an error is made with, besides its code and message. */\nexport interface CryptoAioErrorOptions {\n  readonly cause?: unknown;\n  readonly context?: ErrorContext;\n  readonly details?: Readonly<Record<string, unknown>>;\n  /** Overrides the code's default `retryable` flag. */\n  readonly retryable?: boolean;\n  /** Whether the call may have reached the chain (default `false`). */\n  readonly ambiguous?: boolean;\n}\n\n/** An error as JSON (`toJSON()`), as an Operation stores it. */\nexport interface SerializedError {\n  readonly name: string;\n  readonly code: ErrorCode;\n  readonly category: ErrorCategory;\n  readonly message: string;\n  readonly retryable: boolean;\n  readonly ambiguous: boolean;\n  readonly context: ErrorContext;\n  readonly details?: Readonly<Record<string, unknown>>;\n}\n\n/**\n * Every failure the library reports. Match on `code` and `category`, and on the `details`\n * and `context` fields the Errors reference lists; message texts are not covered by\n * semver.\n */\nexport class CryptoAioError extends Error {\n  readonly code: ErrorCode;\n  readonly category: ErrorCategory;\n  /** Whether the same call may succeed if made again. */\n  readonly retryable: boolean;\n  /** Whether the call may have reached the chain, so its effect is unknown. */\n  readonly ambiguous: boolean;\n  /** Redacted ids of where it happened, such as `operationId`. */\n  readonly context: ErrorContext;\n  /** Code-specific facts, such as `required` and `available` for `INSUFFICIENT_FUNDS`. */\n  readonly details?: Readonly<Record<string, unknown>>;\n\n  constructor(code: ErrorCode, message: string, options: CryptoAioErrorOptions = {}) {\n    super(message, options.cause === undefined ? undefined : { cause: options.cause });\n    this.name = new.target.name;\n    const definition = ERROR_CODES[code];\n    this.code = code;\n    this.category = definition.category;\n    this.retryable = options.retryable ?? definition.retryable;\n    this.ambiguous = options.ambiguous ?? false;\n    this.context = Object.freeze({ ...options.context });\n    if (options.details) this.details = Object.freeze({ ...options.details });\n  }\n\n  /** The error as plain data, without its stack or cause. */\n  toJSON(): SerializedError {\n    return {\n      name: this.name,\n      code: this.code,\n      category: this.category,\n      message: this.message,\n      retryable: this.retryable,\n      ambiguous: this.ambiguous,\n      context: this.context,\n      ...(this.details ? { details: this.details } : {}),\n    };\n  }\n}\n\n/** A configuration that cannot work: an invalid option, a missing SDK package, an incompatible selection. */\nexport class ConfigError extends CryptoAioError {\n  constructor(code: CodesOf<'config'>, message: string, options?: CryptoAioErrorOptions) {\n    super(code, message, options);\n  }\n}\n/** An operation the selected chain, network or library does not support. */\nexport class UnsupportedCapabilityError extends CryptoAioError {\n  constructor(\n    code: CodesOf<'unsupported'>,\n    message: string,\n    options?: CryptoAioErrorOptions,\n  ) {\n    super(code, message, options);\n  }\n}\n/** An input that is not valid: an address, an amount, an asset or an intent. */\nexport class ValidationError extends CryptoAioError {\n  constructor(\n    code: CodesOf<'validation'>,\n    message: string,\n    options?: CryptoAioErrorOptions,\n  ) {\n    super(code, message, options);\n  }\n}\n/** A failure of the endpoints: unavailable, rate-limited, misconfigured, inconsistent, or a definitive refusal. */\nexport class ProviderError extends CryptoAioError {\n  constructor(\n    code: CodesOf<'provider'>,\n    message: string,\n    options?: CryptoAioErrorOptions,\n  ) {\n    super(code, message, options);\n  }\n}\n/** An answer of the chain about a transaction: funds, nonce, fee, refusal, revert, expiry, replacement. */\nexport class ChainError extends CryptoAioError {\n  constructor(code: CodesOf<'chain'>, message: string, options?: CryptoAioErrorOptions) {\n    super(code, message, options);\n  }\n}\n/** A failure to sign: no signer, a failed or mismatched signature, a policy veto, a key that cannot be exported. */\nexport class SigningError extends CryptoAioError {\n  constructor(\n    code: CodesOf<'signing'>,\n    message: string,\n    options?: CryptoAioErrorOptions,\n  ) {\n    super(code, message, options);\n  }\n}\n/** A conflict with stored state: idempotency, fencing, versions, transitions, leases, record formats. */\nexport class StateError extends CryptoAioError {\n  constructor(code: CodesOf<'state'>, message: string, options?: CryptoAioErrorOptions) {\n    super(code, message, options);\n  }\n}\n/** A call that ran out of time. */\nexport class TimeoutError extends CryptoAioError {\n  constructor(\n    code: CodesOf<'timeout'>,\n    message: string,\n    options?: CryptoAioErrorOptions,\n  ) {\n    super(code, message, options);\n  }\n}\n\ntype AnyErrorConstructor = new (\n  code: ErrorCode,\n  message: string,\n  options?: CryptoAioErrorOptions,\n) => CryptoAioError;\n\nconst BY_CATEGORY: Record<ErrorCategory, AnyErrorConstructor> = {\n  config: ConfigError as AnyErrorConstructor,\n  unsupported: UnsupportedCapabilityError as AnyErrorConstructor,\n  validation: ValidationError as AnyErrorConstructor,\n  provider: ProviderError as AnyErrorConstructor,\n  chain: ChainError as AnyErrorConstructor,\n  signing: SigningError as AnyErrorConstructor,\n  state: StateError as AnyErrorConstructor,\n  timeout: TimeoutError as AnyErrorConstructor,\n};\n\n/** An error of `code`'s class. */\nexport function createError(\n  code: ErrorCode,\n  message: string,\n  options?: CryptoAioErrorOptions,\n): CryptoAioError {\n  const Ctor = BY_CATEGORY[ERROR_CODES[code].category];\n  return new Ctor(code, message, options);\n}\n\n/** Whether `value` is a `CryptoAioError`, of `code` when given. */\nexport function isCryptoAioError(\n  value: unknown,\n  code?: ErrorCode,\n): value is CryptoAioError {\n  return value instanceof CryptoAioError && (code === undefined || value.code === code);\n}\n\n/**\n * Returns a copy of `error` (same class, same stack) with merged context, and optional flag\n * and `details` overrides. The copy keeps the stack of the error it reports.\n */\nexport function withContext(\n  error: CryptoAioError,\n  context: ErrorContext,\n  overrides: {\n    readonly ambiguous?: boolean;\n    readonly retryable?: boolean;\n    readonly details?: Readonly<Record<string, unknown>>;\n  } = {},\n): CryptoAioError {\n  const Ctor = error.constructor as AnyErrorConstructor;\n  const details = overrides.details ?? error.details;\n  const copy = new Ctor(error.code, error.message, {\n    cause: error.cause,\n    context: { ...error.context, ...context },\n    ...(details ? { details } : {}),\n    retryable: overrides.retryable ?? error.retryable,\n    ambiguous: overrides.ambiguous ?? error.ambiguous,\n  });\n  if (error.stack !== undefined) {\n    Object.defineProperty(copy, 'stack', {\n      value: error.stack,\n      writable: true,\n      configurable: true,\n    });\n  }\n  return copy;\n}\n"]}

package/dist/core/events/logger.d.ts

@@ -1,13 +1,29 @@
+/** A log entry's severity. */
 export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/** A log entry's structured fields. */
 export type LogFields = Readonly<Record<string, unknown>>;
+/**
+ * Where the library logs (`AioOptions.logger`). A port you may implement: it never gains a
+ * required member in a 1.x release. `createLogger` builds one that redacts before writing;
+ * one of your own should redact too, since fields can carry endpoint URLs.
+ */
 export interface Logger {
     debug(message: string, fields?: LogFields): void;
     info(message: string, fields?: LogFields): void;
     warn(message: string, fields?: LogFields): void;
     error(message: string, fields?: LogFields): void;
+    /** A logger for a sub-namespace, such as `transport`. */
     child(namespace: string): Logger;
 }
+/**
+ * Writes one redacted entry, for `createLogger`. A port you may implement: it never gains
+ * a required parameter in a 1.x release.
+ */
 export type LogWriter = (level: LogLevel, namespace: string, message: string, fields?: Record<string, unknown>) => void;
-/** Structured logger; fields are always redacted before they reach the writer. */
+/**
+ * Structured logger; fields are always redacted before they reach the writer. The default
+ * writer logs through `debug` under `<namespace>:<level>`.
+ */
 export declare function createLogger(namespace?: string, write?: LogWriter): Logger;
+/** A logger that drops everything. */
 export declare const noopLogger: Logger;

package/dist/core/events/logger.js

@@ -20,7 +20,10 @@ const debugWriter = (level, namespace, message, fields) => {
     else
         log('%s', message);
 };
-/** Structured logger; fields are always redacted before they reach the writer. */
+/**
+ * Structured logger; fields are always redacted before they reach the writer. The default
+ * writer logs through `debug` under `<namespace>:<level>`.
+ */
 function createLogger(namespace = 'crypto-aio', write = debugWriter) {
     const emit = (level) => (message, fields) => write(level, namespace, (0, redact_1.redactText)(message), fields ? (0, redact_1.redactDeep)(fields) : undefined);
     return {
@@ -32,6 +35,7 @@ function createLogger(namespace = 'crypto-aio', write = debugWriter) {
     };
 }
 const noop = () => undefined;
+/** A logger that drops everything. */
 exports.noopLogger = {
     debug: noop,
     info: noop,

package/dist/core/events/logger.js.map

@@ -1 +1 @@
-{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../../src/core/events/logger.ts"],"names":[],"mappings":";;;;;;AAmCA,oCAkBC;AArDD,kDAAgC;AAChC,6CAA0D;AAoB1D,MAAM,SAAS,GAAG,IAAI,GAAG,EAAgC,CAAC;AAE1D,MAAM,WAAW,GAAc,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE;IACnE,MAAM,IAAI,GAAG,GAAG,SAAS,IAAI,KAAK,EAAE,CAAC;IACrC,IAAI,GAAG,GAAG,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,GAAG,GAAG,IAAA,eAAW,EAAC,IAAI,CAAC,CAAC;QACxB,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC3B,CAAC;IACD,IAAI,MAAM,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,GAAG,CAAC;QAAE,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;;QACvE,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AAC1B,CAAC,CAAC;AAEF,kFAAkF;AAClF,SAAgB,YAAY,CAC1B,SAAS,GAAG,YAAY,EACxB,QAAmB,WAAW;IAE9B,MAAM,IAAI,GAAG,CAAC,KAAe,EAAE,EAAE,CAAC,CAAC,OAAe,EAAE,MAAkB,EAAE,EAAE,CACxE,KAAK,CACH,KAAK,EACL,SAAS,EACT,IAAA,mBAAU,EAAC,OAAO,CAAC,EACnB,MAAM,CAAC,CAAC,CAAE,IAAA,mBAAU,EAAC,MAAM,CAA6B,CAAC,CAAC,CAAC,SAAS,CACrE,CAAC;IACJ,OAAO;QACL,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC;QACpB,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC;QAClB,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC;QAClB,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC;QACpB,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,SAAS,IAAI,KAAK,EAAE,EAAE,KAAK,CAAC;KAC/D,CAAC;AACJ,CAAC;AAED,MAAM,IAAI,GAAG,GAAS,EAAE,CAAC,SAAS,CAAC;AAEtB,QAAA,UAAU,GAAW;IAChC,KAAK,EAAE,IAAI;IACX,IAAI,EAAE,IAAI;IACV,IAAI,EAAE,IAAI;IACV,KAAK,EAAE,IAAI;IACX,KAAK,EAAE,GAAG,EAAE,CAAC,kBAAU;CACxB,CAAC","sourcesContent":["import createDebug from 'debug';\nimport { redactDeep, redactText } from '../secret/redact';\n\nexport type LogLevel = 'debug' | 'info' | 'warn' | 'error';\nexport type LogFields = Readonly<Record<string, unknown>>;\n\nexport interface Logger {\n  debug(message: string, fields?: LogFields): void;\n  info(message: string, fields?: LogFields): void;\n  warn(message: string, fields?: LogFields): void;\n  error(message: string, fields?: LogFields): void;\n  child(namespace: string): Logger;\n}\n\nexport type LogWriter = (\n  level: LogLevel,\n  namespace: string,\n  message: string,\n  fields?: Record<string, unknown>,\n) => void;\n\nconst debuggers = new Map<string, createDebug.Debugger>();\n\nconst debugWriter: LogWriter = (level, namespace, message, fields) => {\n  const name = `${namespace}:${level}`;\n  let log = debuggers.get(name);\n  if (!log) {\n    log = createDebug(name);\n    debuggers.set(name, log);\n  }\n  if (fields && Object.keys(fields).length > 0) log('%s %o', message, fields);\n  else log('%s', message);\n};\n\n/** Structured logger; fields are always redacted before they reach the writer. */\nexport function createLogger(\n  namespace = 'crypto-aio',\n  write: LogWriter = debugWriter,\n): Logger {\n  const emit = (level: LogLevel) => (message: string, fields?: LogFields) =>\n    write(\n      level,\n      namespace,\n      redactText(message),\n      fields ? (redactDeep(fields) as Record<string, unknown>) : undefined,\n    );\n  return {\n    debug: emit('debug'),\n    info: emit('info'),\n    warn: emit('warn'),\n    error: emit('error'),\n    child: (child) => createLogger(`${namespace}:${child}`, write),\n  };\n}\n\nconst noop = (): void => undefined;\n\nexport const noopLogger: Logger = {\n  debug: noop,\n  info: noop,\n  warn: noop,\n  error: noop,\n  child: () => noopLogger,\n};\n"]}
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../../src/core/events/logger.ts"],"names":[],"mappings":";;;;;;AAkDA,oCAkBC;AApED,kDAAgC;AAChC,6CAA0D;AAgC1D,MAAM,SAAS,GAAG,IAAI,GAAG,EAAgC,CAAC;AAE1D,MAAM,WAAW,GAAc,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE;IACnE,MAAM,IAAI,GAAG,GAAG,SAAS,IAAI,KAAK,EAAE,CAAC;IACrC,IAAI,GAAG,GAAG,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,GAAG,GAAG,IAAA,eAAW,EAAC,IAAI,CAAC,CAAC;QACxB,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC3B,CAAC;IACD,IAAI,MAAM,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,GAAG,CAAC;QAAE,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;;QACvE,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AAC1B,CAAC,CAAC;AAEF;;;GAGG;AACH,SAAgB,YAAY,CAC1B,SAAS,GAAG,YAAY,EACxB,QAAmB,WAAW;IAE9B,MAAM,IAAI,GAAG,CAAC,KAAe,EAAE,EAAE,CAAC,CAAC,OAAe,EAAE,MAAkB,EAAE,EAAE,CACxE,KAAK,CACH,KAAK,EACL,SAAS,EACT,IAAA,mBAAU,EAAC,OAAO,CAAC,EACnB,MAAM,CAAC,CAAC,CAAE,IAAA,mBAAU,EAAC,MAAM,CAA6B,CAAC,CAAC,CAAC,SAAS,CACrE,CAAC;IACJ,OAAO;QACL,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC;QACpB,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC;QAClB,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC;QAClB,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC;QACpB,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,SAAS,IAAI,KAAK,EAAE,EAAE,KAAK,CAAC;KAC/D,CAAC;AACJ,CAAC;AAED,MAAM,IAAI,GAAG,GAAS,EAAE,CAAC,SAAS,CAAC;AAEnC,sCAAsC;AACzB,QAAA,UAAU,GAAW;IAChC,KAAK,EAAE,IAAI;IACX,IAAI,EAAE,IAAI;IACV,IAAI,EAAE,IAAI;IACV,KAAK,EAAE,IAAI;IACX,KAAK,EAAE,GAAG,EAAE,CAAC,kBAAU;CACxB,CAAC","sourcesContent":["import createDebug from 'debug';\nimport { redactDeep, redactText } from '../secret/redact';\n\n/** A log entry's severity. */\nexport type LogLevel = 'debug' | 'info' | 'warn' | 'error';\n/** A log entry's structured fields. */\nexport type LogFields = Readonly<Record<string, unknown>>;\n\n/**\n * Where the library logs (`AioOptions.logger`). A port you may implement: it never gains a\n * required member in a 1.x release. `createLogger` builds one that redacts before writing;\n * one of your own should redact too, since fields can carry endpoint URLs.\n */\nexport interface Logger {\n  debug(message: string, fields?: LogFields): void;\n  info(message: string, fields?: LogFields): void;\n  warn(message: string, fields?: LogFields): void;\n  error(message: string, fields?: LogFields): void;\n  /** A logger for a sub-namespace, such as `transport`. */\n  child(namespace: string): Logger;\n}\n\n/**\n * Writes one redacted entry, for `createLogger`. A port you may implement: it never gains\n * a required parameter in a 1.x release.\n */\nexport type LogWriter = (\n  level: LogLevel,\n  namespace: string,\n  message: string,\n  fields?: Record<string, unknown>,\n) => void;\n\nconst debuggers = new Map<string, createDebug.Debugger>();\n\nconst debugWriter: LogWriter = (level, namespace, message, fields) => {\n  const name = `${namespace}:${level}`;\n  let log = debuggers.get(name);\n  if (!log) {\n    log = createDebug(name);\n    debuggers.set(name, log);\n  }\n  if (fields && Object.keys(fields).length > 0) log('%s %o', message, fields);\n  else log('%s', message);\n};\n\n/**\n * Structured logger; fields are always redacted before they reach the writer. The default\n * writer logs through `debug` under `<namespace>:<level>`.\n */\nexport function createLogger(\n  namespace = 'crypto-aio',\n  write: LogWriter = debugWriter,\n): Logger {\n  const emit = (level: LogLevel) => (message: string, fields?: LogFields) =>\n    write(\n      level,\n      namespace,\n      redactText(message),\n      fields ? (redactDeep(fields) as Record<string, unknown>) : undefined,\n    );\n  return {\n    debug: emit('debug'),\n    info: emit('info'),\n    warn: emit('warn'),\n    error: emit('error'),\n    child: (child) => createLogger(`${namespace}:${child}`, write),\n  };\n}\n\nconst noop = (): void => undefined;\n\n/** A logger that drops everything. */\nexport const noopLogger: Logger = {\n  debug: noop,\n  info: noop,\n  warn: noop,\n  error: noop,\n  child: () => noopLogger,\n};\n"]}

package/dist/core/events/types.d.ts

@@ -1,13 +1,18 @@
 import type { Evidence, TxState } from '../model/transaction';
 import type { OperationState } from '../store/types';
-/** Every payload is operational-class data only (no addresses, amounts, raw txs or URLs). */
+/**
+ * Every event and its payload. Every payload is operational-class data only (no addresses,
+ * amounts, raw txs or URLs). A minor release may add events and optional payload fields.
+ */
 export interface AioEvents {
+    /** A request is about to go to an endpoint; `method` is an RPC method or a route template. */
     'rpc.request': {
         transportId: string;
         endpointId: string;
         method: string;
         attempt: number;
     };
+    /** An endpoint answered. */
     'rpc.response': {
         transportId: string;
         endpointId: string;
@@ -15,6 +20,7 @@ export interface AioEvents {
         latencyMs: number;
         bytes: number;
     };
+    /** A request to an endpoint failed. */
     'rpc.error': {
         transportId: string;
         endpointId: string;
@@ -23,6 +29,11 @@ export interface AioEvents {
         code: string;
         retryable: boolean;
     };
+    /**
+     * After every completed health refresh, once per endpoint, with its state: a periodic
+     * gauge, not a change event. Never emitted for an endpoint whose state is `unknown` or
+     * `half-open`.
+     */
     'provider.health': {
         transportId: string;
         endpointId: string;
@@ -30,17 +41,20 @@ export interface AioEvents {
         height?: string;
         lag?: string;
     };
+    /** An endpoint answered another network's identity than expected; it is disabled. */
     'provider.misconfigured': {
         transportId: string;
         endpointId: string;
         expected: string;
         actual: string;
     };
+    /** Endpoints of a quorum read disagreed; the read decided nothing. */
     'provider.inconsistent': {
         transportId: string;
         method: string;
         endpointIds: readonly string[];
     };
+    /** An Operation moved from one state to another (`from` is `null` when it was created). */
     'operation.state': {
         namespace: string;
         operationId: string;
@@ -50,11 +64,13 @@ export interface AioEvents {
         to: OperationState;
         code?: string;
     };
+    /** An Operation stalled and waits for its caller's remedy; `code` says why. */
     'operation.stalled': {
         namespace: string;
         operationId: string;
         code: string;
     };
+    /** An Attempt's observed state or evidence changed. */
     'attempt.state': {
         namespace: string;
         operationId: string;
@@ -62,12 +78,14 @@ export interface AioEvents {
         state: TxState;
         evidence: Evidence;
     };
+    /** A block that held a transfer's transaction left the chain. */
     'tx.reorged': {
         namespace: string;
         operationId?: string;
         attemptId?: string;
         previousBlockHash: string;
     };
+    /** A nonce or seqno was reserved for an Operation. */
     'nonce.allocated': {
         namespace: string;
         chain: string;
@@ -91,12 +109,14 @@ export interface AioEvents {
         expected: string;
         blockingOperationId?: string;
     };
+    /** A signer was asked for `requests` signatures. */
     'signer.requested': {
         namespace: string;
         operationId: string;
         signerId: string;
         requests: number;
     };
+    /** A signer answered: signed, pending (with a ticket), or with an error. */
     'signer.completed': {
         namespace: string;
         operationId: string;
@@ -104,17 +124,20 @@ export interface AioEvents {
         status: 'signed' | 'pending' | 'error';
         latencyMs: number;
     };
+    /** A scanner delivered a block. */
     'scanner.block': {
         namespace: string;
         cursorKey: string;
         height: string;
     };
+    /** A scanner rolled back to `toHeight` after a reorg, removing `removed` blocks. */
     'scanner.rollback': {
         namespace: string;
         cursorKey: string;
         toHeight: string;
         removed: number;
     };
+    /** `recover()` left an Operation that needs its caller; `reason` is a code. */
     'recovery.skipped': {
         namespace: string;
         operationId: string;
@@ -122,7 +145,9 @@ export interface AioEvents {
         reason: string;
     };
 }
+/** The name of an event. */
 export type AioEventName = keyof AioEvents;
+/** An event as a listener gets it: its payload, with its `type` and the time `at` it fired. */
 export type AioEvent<E extends AioEventName = AioEventName> = {
     [K in E]: AioEvents[K] & {
         readonly type: K;

package/dist/core/events/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/events/types.ts"],"names":[],"mappings":"","sourcesContent":["import type { Evidence, TxState } from '../model/transaction';\nimport type { OperationState } from '../store/types';\n\n/** Every payload is operational-class data only (no addresses, amounts, raw txs or URLs). */\nexport interface AioEvents {\n  'rpc.request': {\n    transportId: string;\n    endpointId: string;\n    method: string;\n    attempt: number;\n  };\n  'rpc.response': {\n    transportId: string;\n    endpointId: string;\n    method: string;\n    latencyMs: number;\n    bytes: number;\n  };\n  'rpc.error': {\n    transportId: string;\n    endpointId: string;\n    method: string;\n    latencyMs: number;\n    code: string;\n    retryable: boolean;\n  };\n  'provider.health': {\n    transportId: string;\n    endpointId: string;\n    state: 'healthy' | 'lagging' | 'open' | 'disabled';\n    height?: string;\n    lag?: string;\n  };\n  'provider.misconfigured': {\n    transportId: string;\n    endpointId: string;\n    expected: string;\n    actual: string;\n  };\n  'provider.inconsistent': {\n    transportId: string;\n    method: string;\n    endpointIds: readonly string[];\n  };\n  'operation.state': {\n    namespace: string;\n    operationId: string;\n    chain: string;\n    network: string;\n    from: OperationState | null;\n    to: OperationState;\n    code?: string;\n  };\n  'operation.stalled': { namespace: string; operationId: string; code: string };\n  'attempt.state': {\n    namespace: string;\n    operationId: string;\n    attemptId: string;\n    state: TxState;\n    evidence: Evidence;\n  };\n  'tx.reorged': {\n    namespace: string;\n    operationId?: string;\n    attemptId?: string;\n    previousBlockHash: string;\n  };\n  'nonce.allocated': {\n    namespace: string;\n    chain: string;\n    network: string;\n    operationId: string;\n    /** The nonce or seqno: an operational identifier, never UTXO inputs. */\n    value: string;\n  };\n  /**\n   * A submitted Operation has waited past the grace period while the chain's pending nonce\n   * (`expected`) is below its own. At-least-once: a monitor reports each (Operation,\n   * expected) once, but that memory is per process and bounded, so the same gap is reported\n   * again after a restart, by another process, or once it was forgotten.\n   */\n  'nonce.gap': {\n    namespace: string;\n    chain: string;\n    network: string;\n    operationId: string;\n    /** The chain's pending nonce: an operational identifier. */\n    expected: string;\n    blockingOperationId?: string;\n  };\n  'signer.requested': {\n    namespace: string;\n    operationId: string;\n    signerId: string;\n    requests: number;\n  };\n  'signer.completed': {\n    namespace: string;\n    operationId: string;\n    signerId: string;\n    status: 'signed' | 'pending' | 'error';\n    latencyMs: number;\n  };\n  'scanner.block': { namespace: string; cursorKey: string; height: string };\n  'scanner.rollback': {\n    namespace: string;\n    cursorKey: string;\n    toHeight: string;\n    removed: number;\n  };\n  'recovery.skipped': {\n    namespace: string;\n    operationId: string;\n    state: OperationState;\n    reason: string;\n  };\n}\n\nexport type AioEventName = keyof AioEvents;\n\nexport type AioEvent<E extends AioEventName = AioEventName> = {\n  [K in E]: AioEvents[K] & { readonly type: K; readonly at: number };\n}[E];\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/events/types.ts"],"names":[],"mappings":"","sourcesContent":["import type { Evidence, TxState } from '../model/transaction';\nimport type { OperationState } from '../store/types';\n\n/**\n * Every event and its payload. Every payload is operational-class data only (no addresses,\n * amounts, raw txs or URLs). A minor release may add events and optional payload fields.\n */\nexport interface AioEvents {\n  /** A request is about to go to an endpoint; `method` is an RPC method or a route template. */\n  'rpc.request': {\n    transportId: string;\n    endpointId: string;\n    method: string;\n    attempt: number;\n  };\n  /** An endpoint answered. */\n  'rpc.response': {\n    transportId: string;\n    endpointId: string;\n    method: string;\n    latencyMs: number;\n    bytes: number;\n  };\n  /** A request to an endpoint failed. */\n  'rpc.error': {\n    transportId: string;\n    endpointId: string;\n    method: string;\n    latencyMs: number;\n    code: string;\n    retryable: boolean;\n  };\n  /**\n   * After every completed health refresh, once per endpoint, with its state: a periodic\n   * gauge, not a change event. Never emitted for an endpoint whose state is `unknown` or\n   * `half-open`.\n   */\n  'provider.health': {\n    transportId: string;\n    endpointId: string;\n    state: 'healthy' | 'lagging' | 'open' | 'disabled';\n    height?: string;\n    lag?: string;\n  };\n  /** An endpoint answered another network's identity than expected; it is disabled. */\n  'provider.misconfigured': {\n    transportId: string;\n    endpointId: string;\n    expected: string;\n    actual: string;\n  };\n  /** Endpoints of a quorum read disagreed; the read decided nothing. */\n  'provider.inconsistent': {\n    transportId: string;\n    method: string;\n    endpointIds: readonly string[];\n  };\n  /** An Operation moved from one state to another (`from` is `null` when it was created). */\n  'operation.state': {\n    namespace: string;\n    operationId: string;\n    chain: string;\n    network: string;\n    from: OperationState | null;\n    to: OperationState;\n    code?: string;\n  };\n  /** An Operation stalled and waits for its caller's remedy; `code` says why. */\n  'operation.stalled': { namespace: string; operationId: string; code: string };\n  /** An Attempt's observed state or evidence changed. */\n  'attempt.state': {\n    namespace: string;\n    operationId: string;\n    attemptId: string;\n    state: TxState;\n    evidence: Evidence;\n  };\n  /** A block that held a transfer's transaction left the chain. */\n  'tx.reorged': {\n    namespace: string;\n    operationId?: string;\n    attemptId?: string;\n    previousBlockHash: string;\n  };\n  /** A nonce or seqno was reserved for an Operation. */\n  'nonce.allocated': {\n    namespace: string;\n    chain: string;\n    network: string;\n    operationId: string;\n    /** The nonce or seqno: an operational identifier, never UTXO inputs. */\n    value: string;\n  };\n  /**\n   * A submitted Operation has waited past the grace period while the chain's pending nonce\n   * (`expected`) is below its own. At-least-once: a monitor reports each (Operation,\n   * expected) once, but that memory is per process and bounded, so the same gap is reported\n   * again after a restart, by another process, or once it was forgotten.\n   */\n  'nonce.gap': {\n    namespace: string;\n    chain: string;\n    network: string;\n    operationId: string;\n    /** The chain's pending nonce: an operational identifier. */\n    expected: string;\n    blockingOperationId?: string;\n  };\n  /** A signer was asked for `requests` signatures. */\n  'signer.requested': {\n    namespace: string;\n    operationId: string;\n    signerId: string;\n    requests: number;\n  };\n  /** A signer answered: signed, pending (with a ticket), or with an error. */\n  'signer.completed': {\n    namespace: string;\n    operationId: string;\n    signerId: string;\n    status: 'signed' | 'pending' | 'error';\n    latencyMs: number;\n  };\n  /** A scanner delivered a block. */\n  'scanner.block': { namespace: string; cursorKey: string; height: string };\n  /** A scanner rolled back to `toHeight` after a reorg, removing `removed` blocks. */\n  'scanner.rollback': {\n    namespace: string;\n    cursorKey: string;\n    toHeight: string;\n    removed: number;\n  };\n  /** `recover()` left an Operation that needs its caller; `reason` is a code. */\n  'recovery.skipped': {\n    namespace: string;\n    operationId: string;\n    state: OperationState;\n    reason: string;\n  };\n}\n\n/** The name of an event. */\nexport type AioEventName = keyof AioEvents;\n\n/** An event as a listener gets it: its payload, with its `type` and the time `at` it fired. */\nexport type AioEvent<E extends AioEventName = AioEventName> = {\n  [K in E]: AioEvents[K] & { readonly type: K; readonly at: number };\n}[E];\n"]}

package/dist/core/lifecycle/engine.d.ts

@@ -27,6 +27,11 @@ export interface OperationTarget extends ReadTarget {
     readonly wallet: ResolvedWallet;
     readonly assets: AssetService;
 }
+/**
+ * Options of `bc.transfer()` and its kin: the `idempotencyKey` that makes a repeat return
+ * the same Operation (1 to 200 characters of well-formed text without U+0000; one is
+ * generated when absent), and a `signal` that stops waiting, never a payment already sent.
+ */
 export interface TransferOptions {
     readonly idempotencyKey?: string;
     readonly signal?: AbortSignal;