@ensnode/ponder-sdk 1.9.0 → 1.10.0

package/dist/index.d.cts

@@ -209,6 +209,127 @@ type ChainId = z.infer<typeof schemaChainId>;
  */
 type ChainIdString = string;
 
+/**
+ * Represents a single log entry for the Ponder app logger.
+ *
+ * It is a loose object that:
+ * - must contain a `msg` property of type string, and
+ * - can optionally include an `error` property of type Error, and
+ * - can optionally include any additional properties relevant to
+ *   the log message. The additional properties can be used to provide more
+ *   context about the log message, and will be included in the log output.
+ */
+type PonderAppLog = {
+    /**
+     * Log message
+     */
+    msg: string;
+    /**
+     * Optional error object to log.
+     *
+     * If provided, the logger will log the error's stack trace and message.
+     */
+    error?: unknown;
+    /**
+     * Optional additional properties.
+     *
+     * If provided, they will be included in the log output.
+     */
+    [key: string]: unknown;
+};
+/**
+ * Ponder app logger
+ *
+ * Represents the logger provided by the Ponder runtime to a local Ponder app.
+ * @see https://github.com/ponder-sh/ponder/blob/6fcc15d4234e43862cb6e21c05f3c57f4c2f7464/packages/core/src/internal/logger.ts#L8-L31
+ */
+interface PonderAppLogger {
+    /**
+     * Logs a message at the "error" level.
+     *
+     * @param options - The log message and additional properties to log.
+     *
+     * @example
+     * ```ts
+     * logger.error({
+     *   msg: "Incorrect omnichain status",
+     *   error: new Error("The omnichain status must be either 'omnichain-backfill' or 'omnichain-following'"),
+     *    expected: "omnichain-backfill or omnichain-following",
+     *    actual: "omnichain-unstarted"
+     * });
+     *
+     * logger.error({
+     *   msg: "Incorrect omnichain status",
+     *   error: new Error("The omnichain status must be either 'omnichain-backfill' or 'omnichain-following'"),
+     * });
+     *
+     * logger.error({
+     *   msg: "The omnichain status must be either 'omnichain-backfill' or 'omnichain-following'"
+     * });
+     * ```
+     */
+    error<T extends PonderAppLog>(options: T): void;
+    /**
+     * Logs a message at the "warn" level.
+     *
+     * @param options - The log message and additional properties to log.
+     *
+     * @example
+     * ```ts
+     * logger.warn({
+     *   msg: "Both the '${PluginName.Subgraph}' and '${PluginName.ENSv2}' plugins are enabled.",
+     *   effects: "This results in the availability of both the legacy Subgraph-Compatible GraphQL API (/subgraph) _and_ ENSNode's Omnigraph API (/api/omnigraph), and comes with an associated increase in indexing time. If your intent is to have both APIs available in parallel, excellent, otherwise you may benefit from only enabling the plugin for the API you plan to use."
+     * });
+     *
+     * logger.warn({
+     *   msg: "Both the '${PluginName.Subgraph}' and '${PluginName.ENSv2}' plugins are enabled."
+     * });
+     * ```
+     */
+    warn<T extends PonderAppLog>(options: T): void;
+    /**
+     * Logs a message at the "info" level.
+     * @param options
+     *
+     * @example
+     * ```ts
+     * logger.info({
+     *   msg: "An informational message",
+     *   details: "Here are some details about the info"
+     * });
+     * ```
+     */
+    info<T extends PonderAppLog>(options: T): void;
+    /**
+     * Logs a message at the "debug" level.
+     * @param options
+     *
+     * @example
+     * ```ts
+     * logger.debug({
+     *   msg: "A debug message",
+     *   arg1: "Here is some debug information about arg1",
+     *   arg2: "Here is some debug information about arg2"
+     * });
+     * ```
+     */
+    debug<T extends PonderAppLog>(options: T): void;
+    /**
+     * Logs a message at the "trace" level.
+     * @param options
+     *
+     * @example
+     * ```ts
+     * logger.trace({
+     *   msg: "A trace message",
+     *   detailA: "Here are some details about the trace message",
+     *   detailB: "Here are some more details about the trace message"
+     * });
+     * ```
+     */
+    trace<T extends PonderAppLog>(options: T): void;
+}
+
 /**
  * Ponder app commands
  *
@@ -233,6 +354,10 @@ interface PonderAppContext {
      * URL of the local Ponder app.
      */
     localPonderAppUrl: URL;
+    /**
+     * Logger provided by the Ponder runtime
+     */
+    logger: PonderAppLogger;
 }
 
 /**
@@ -519,6 +644,28 @@ declare const schemaRawPonderAppContext: z.ZodObject<{
         }>;
         port: z.ZodNumber;
     }, z.core.$strip>;
+    logger: z.ZodObject<{
+        error: z.ZodFunction<z.ZodTuple<readonly [z.ZodObject<{
+            msg: z.ZodString;
+            error: z.ZodOptional<z.ZodUnknown>;
+        }, z.core.$loose>], null>, z.ZodVoid>;
+        warn: z.ZodFunction<z.ZodTuple<readonly [z.ZodObject<{
+            msg: z.ZodString;
+            error: z.ZodOptional<z.ZodUnknown>;
+        }, z.core.$loose>], null>, z.ZodVoid>;
+        info: z.ZodFunction<z.ZodTuple<readonly [z.ZodObject<{
+            msg: z.ZodString;
+            error: z.ZodOptional<z.ZodUnknown>;
+        }, z.core.$loose>], null>, z.ZodVoid>;
+        debug: z.ZodFunction<z.ZodTuple<readonly [z.ZodObject<{
+            msg: z.ZodString;
+            error: z.ZodOptional<z.ZodUnknown>;
+        }, z.core.$loose>], null>, z.ZodVoid>;
+        trace: z.ZodFunction<z.ZodTuple<readonly [z.ZodObject<{
+            msg: z.ZodString;
+            error: z.ZodOptional<z.ZodUnknown>;
+        }, z.core.$loose>], null>, z.ZodVoid>;
+    }, z.core.$loose>;
 }, z.core.$strip>;
 /**
  * Type representing the "raw" context of a local Ponder app.
@@ -770,4 +917,4 @@ declare const schemaUnixTimestamp: z.ZodNumber;
  */
 type UnixTimestamp = z.infer<typeof schemaUnixTimestamp>;
 
-export { type BlockNumber, type BlockNumberRange, type BlockNumberRangeBounded, type BlockNumberRangeLeftBounded, type BlockNumberRangeRightBounded, type BlockNumberRangeUnbounded, type BlockNumberRangeWithStartBlock, type BlockRef, type BlockRefRange, type BlockRefRangeBounded, type BlockRefRangeLeftBounded, type BlockRefRangeRightBounded, type BlockRefRangeUnbounded, type BlockRefRangeWithStartBlock, type ChainId, type ChainIdString, type ChainIndexingConfig, type ChainIndexingMetrics, type ChainIndexingMetricsCompleted, type ChainIndexingMetricsHistorical, type ChainIndexingMetricsRealtime, type ChainIndexingState, ChainIndexingStates, type ChainIndexingStatus, type LocalChainIndexingMetrics, type LocalChainIndexingMetricsHistorical, LocalPonderClient, type LocalPonderIndexingMetrics, type PonderAppCommand, PonderAppCommands, type PonderAppContext, type PonderApplicationSettings, type PonderBlockNumberRange, PonderClient, type PonderIndexingMetrics, type PonderIndexingOrdering, PonderIndexingOrderings, type PonderIndexingStatus, type RangeType, RangeTypeIds, type RawPonderAppContext, type UnixTimestamp, buildBlockNumberRange, buildBlockRefRange, deserializePonderAppContext, isBlockRefBefore, isBlockRefBeforeOrEqualTo, isBlockRefEqualTo, mergeBlockNumberRanges, schemaBlockNumber, schemaBlockRef, schemaChainId, schemaInteger, schemaNonnegativeInteger, schemaNonnegativeNumber, schemaNumber, schemaPortNumber, schemaPositiveInteger, schemaPositiveNumber, schemaUnixTimestamp };
+export { type BlockNumber, type BlockNumberRange, type BlockNumberRangeBounded, type BlockNumberRangeLeftBounded, type BlockNumberRangeRightBounded, type BlockNumberRangeUnbounded, type BlockNumberRangeWithStartBlock, type BlockRef, type BlockRefRange, type BlockRefRangeBounded, type BlockRefRangeLeftBounded, type BlockRefRangeRightBounded, type BlockRefRangeUnbounded, type BlockRefRangeWithStartBlock, type ChainId, type ChainIdString, type ChainIndexingConfig, type ChainIndexingMetrics, type ChainIndexingMetricsCompleted, type ChainIndexingMetricsHistorical, type ChainIndexingMetricsRealtime, type ChainIndexingState, ChainIndexingStates, type ChainIndexingStatus, type LocalChainIndexingMetrics, type LocalChainIndexingMetricsHistorical, LocalPonderClient, type LocalPonderIndexingMetrics, type PonderAppCommand, PonderAppCommands, type PonderAppContext, type PonderAppLog, type PonderAppLogger, type PonderApplicationSettings, type PonderBlockNumberRange, PonderClient, type PonderIndexingMetrics, type PonderIndexingOrdering, PonderIndexingOrderings, type PonderIndexingStatus, type RangeType, RangeTypeIds, type RawPonderAppContext, type UnixTimestamp, buildBlockNumberRange, buildBlockRefRange, deserializePonderAppContext, isBlockRefBefore, isBlockRefBeforeOrEqualTo, isBlockRefEqualTo, mergeBlockNumberRanges, schemaBlockNumber, schemaBlockRef, schemaChainId, schemaInteger, schemaNonnegativeInteger, schemaNonnegativeNumber, schemaNumber, schemaPortNumber, schemaPositiveInteger, schemaPositiveNumber, schemaUnixTimestamp };

package/dist/index.d.ts

@@ -209,6 +209,127 @@ type ChainId = z.infer<typeof schemaChainId>;
  */
 type ChainIdString = string;
 
+/**
+ * Represents a single log entry for the Ponder app logger.
+ *
+ * It is a loose object that:
+ * - must contain a `msg` property of type string, and
+ * - can optionally include an `error` property of type Error, and
+ * - can optionally include any additional properties relevant to
+ *   the log message. The additional properties can be used to provide more
+ *   context about the log message, and will be included in the log output.
+ */
+type PonderAppLog = {
+    /**
+     * Log message
+     */
+    msg: string;
+    /**
+     * Optional error object to log.
+     *
+     * If provided, the logger will log the error's stack trace and message.
+     */
+    error?: unknown;
+    /**
+     * Optional additional properties.
+     *
+     * If provided, they will be included in the log output.
+     */
+    [key: string]: unknown;
+};
+/**
+ * Ponder app logger
+ *
+ * Represents the logger provided by the Ponder runtime to a local Ponder app.
+ * @see https://github.com/ponder-sh/ponder/blob/6fcc15d4234e43862cb6e21c05f3c57f4c2f7464/packages/core/src/internal/logger.ts#L8-L31
+ */
+interface PonderAppLogger {
+    /**
+     * Logs a message at the "error" level.
+     *
+     * @param options - The log message and additional properties to log.
+     *
+     * @example
+     * ```ts
+     * logger.error({
+     *   msg: "Incorrect omnichain status",
+     *   error: new Error("The omnichain status must be either 'omnichain-backfill' or 'omnichain-following'"),
+     *    expected: "omnichain-backfill or omnichain-following",
+     *    actual: "omnichain-unstarted"
+     * });
+     *
+     * logger.error({
+     *   msg: "Incorrect omnichain status",
+     *   error: new Error("The omnichain status must be either 'omnichain-backfill' or 'omnichain-following'"),
+     * });
+     *
+     * logger.error({
+     *   msg: "The omnichain status must be either 'omnichain-backfill' or 'omnichain-following'"
+     * });
+     * ```
+     */
+    error<T extends PonderAppLog>(options: T): void;
+    /**
+     * Logs a message at the "warn" level.
+     *
+     * @param options - The log message and additional properties to log.
+     *
+     * @example
+     * ```ts
+     * logger.warn({
+     *   msg: "Both the '${PluginName.Subgraph}' and '${PluginName.ENSv2}' plugins are enabled.",
+     *   effects: "This results in the availability of both the legacy Subgraph-Compatible GraphQL API (/subgraph) _and_ ENSNode's Omnigraph API (/api/omnigraph), and comes with an associated increase in indexing time. If your intent is to have both APIs available in parallel, excellent, otherwise you may benefit from only enabling the plugin for the API you plan to use."
+     * });
+     *
+     * logger.warn({
+     *   msg: "Both the '${PluginName.Subgraph}' and '${PluginName.ENSv2}' plugins are enabled."
+     * });
+     * ```
+     */
+    warn<T extends PonderAppLog>(options: T): void;
+    /**
+     * Logs a message at the "info" level.
+     * @param options
+     *
+     * @example
+     * ```ts
+     * logger.info({
+     *   msg: "An informational message",
+     *   details: "Here are some details about the info"
+     * });
+     * ```
+     */
+    info<T extends PonderAppLog>(options: T): void;
+    /**
+     * Logs a message at the "debug" level.
+     * @param options
+     *
+     * @example
+     * ```ts
+     * logger.debug({
+     *   msg: "A debug message",
+     *   arg1: "Here is some debug information about arg1",
+     *   arg2: "Here is some debug information about arg2"
+     * });
+     * ```
+     */
+    debug<T extends PonderAppLog>(options: T): void;
+    /**
+     * Logs a message at the "trace" level.
+     * @param options
+     *
+     * @example
+     * ```ts
+     * logger.trace({
+     *   msg: "A trace message",
+     *   detailA: "Here are some details about the trace message",
+     *   detailB: "Here are some more details about the trace message"
+     * });
+     * ```
+     */
+    trace<T extends PonderAppLog>(options: T): void;
+}
+
 /**
  * Ponder app commands
  *
@@ -233,6 +354,10 @@ interface PonderAppContext {
      * URL of the local Ponder app.
      */
     localPonderAppUrl: URL;
+    /**
+     * Logger provided by the Ponder runtime
+     */
+    logger: PonderAppLogger;
 }
 
 /**
@@ -519,6 +644,28 @@ declare const schemaRawPonderAppContext: z.ZodObject<{
         }>;
         port: z.ZodNumber;
     }, z.core.$strip>;
+    logger: z.ZodObject<{
+        error: z.ZodFunction<z.ZodTuple<readonly [z.ZodObject<{
+            msg: z.ZodString;
+            error: z.ZodOptional<z.ZodUnknown>;
+        }, z.core.$loose>], null>, z.ZodVoid>;
+        warn: z.ZodFunction<z.ZodTuple<readonly [z.ZodObject<{
+            msg: z.ZodString;
+            error: z.ZodOptional<z.ZodUnknown>;
+        }, z.core.$loose>], null>, z.ZodVoid>;
+        info: z.ZodFunction<z.ZodTuple<readonly [z.ZodObject<{
+            msg: z.ZodString;
+            error: z.ZodOptional<z.ZodUnknown>;
+        }, z.core.$loose>], null>, z.ZodVoid>;
+        debug: z.ZodFunction<z.ZodTuple<readonly [z.ZodObject<{
+            msg: z.ZodString;
+            error: z.ZodOptional<z.ZodUnknown>;
+        }, z.core.$loose>], null>, z.ZodVoid>;
+        trace: z.ZodFunction<z.ZodTuple<readonly [z.ZodObject<{
+            msg: z.ZodString;
+            error: z.ZodOptional<z.ZodUnknown>;
+        }, z.core.$loose>], null>, z.ZodVoid>;
+    }, z.core.$loose>;
 }, z.core.$strip>;
 /**
  * Type representing the "raw" context of a local Ponder app.
@@ -770,4 +917,4 @@ declare const schemaUnixTimestamp: z.ZodNumber;
  */
 type UnixTimestamp = z.infer<typeof schemaUnixTimestamp>;
 
-export { type BlockNumber, type BlockNumberRange, type BlockNumberRangeBounded, type BlockNumberRangeLeftBounded, type BlockNumberRangeRightBounded, type BlockNumberRangeUnbounded, type BlockNumberRangeWithStartBlock, type BlockRef, type BlockRefRange, type BlockRefRangeBounded, type BlockRefRangeLeftBounded, type BlockRefRangeRightBounded, type BlockRefRangeUnbounded, type BlockRefRangeWithStartBlock, type ChainId, type ChainIdString, type ChainIndexingConfig, type ChainIndexingMetrics, type ChainIndexingMetricsCompleted, type ChainIndexingMetricsHistorical, type ChainIndexingMetricsRealtime, type ChainIndexingState, ChainIndexingStates, type ChainIndexingStatus, type LocalChainIndexingMetrics, type LocalChainIndexingMetricsHistorical, LocalPonderClient, type LocalPonderIndexingMetrics, type PonderAppCommand, PonderAppCommands, type PonderAppContext, type PonderApplicationSettings, type PonderBlockNumberRange, PonderClient, type PonderIndexingMetrics, type PonderIndexingOrdering, PonderIndexingOrderings, type PonderIndexingStatus, type RangeType, RangeTypeIds, type RawPonderAppContext, type UnixTimestamp, buildBlockNumberRange, buildBlockRefRange, deserializePonderAppContext, isBlockRefBefore, isBlockRefBeforeOrEqualTo, isBlockRefEqualTo, mergeBlockNumberRanges, schemaBlockNumber, schemaBlockRef, schemaChainId, schemaInteger, schemaNonnegativeInteger, schemaNonnegativeNumber, schemaNumber, schemaPortNumber, schemaPositiveInteger, schemaPositiveNumber, schemaUnixTimestamp };
+export { type BlockNumber, type BlockNumberRange, type BlockNumberRangeBounded, type BlockNumberRangeLeftBounded, type BlockNumberRangeRightBounded, type BlockNumberRangeUnbounded, type BlockNumberRangeWithStartBlock, type BlockRef, type BlockRefRange, type BlockRefRangeBounded, type BlockRefRangeLeftBounded, type BlockRefRangeRightBounded, type BlockRefRangeUnbounded, type BlockRefRangeWithStartBlock, type ChainId, type ChainIdString, type ChainIndexingConfig, type ChainIndexingMetrics, type ChainIndexingMetricsCompleted, type ChainIndexingMetricsHistorical, type ChainIndexingMetricsRealtime, type ChainIndexingState, ChainIndexingStates, type ChainIndexingStatus, type LocalChainIndexingMetrics, type LocalChainIndexingMetricsHistorical, LocalPonderClient, type LocalPonderIndexingMetrics, type PonderAppCommand, PonderAppCommands, type PonderAppContext, type PonderAppLog, type PonderAppLogger, type PonderApplicationSettings, type PonderBlockNumberRange, PonderClient, type PonderIndexingMetrics, type PonderIndexingOrdering, PonderIndexingOrderings, type PonderIndexingStatus, type RangeType, RangeTypeIds, type RawPonderAppContext, type UnixTimestamp, buildBlockNumberRange, buildBlockRefRange, deserializePonderAppContext, isBlockRefBefore, isBlockRefBeforeOrEqualTo, isBlockRefEqualTo, mergeBlockNumberRanges, schemaBlockNumber, schemaBlockRef, schemaChainId, schemaInteger, schemaNonnegativeInteger, schemaNonnegativeNumber, schemaNumber, schemaPortNumber, schemaPositiveInteger, schemaPositiveNumber, schemaUnixTimestamp };

package/dist/index.js

@@ -1074,21 +1074,85 @@ var PonderClient = class {
 
 // src/deserialize/ponder-app-context.ts
 import { prettifyError as prettifyError3, z as z6 } from "zod/v4";
+
+// src/deserialize/ponder-app-logger.ts
+function isPrimitive(value) {
+  return value === null || typeof value !== "object" && typeof value !== "function";
+}
+function replacer(_key, value) {
+  if (typeof value === "bigint") return value.toString();
+  if (value instanceof URL) return value.href;
+  if (value instanceof Map) return Object.fromEntries(value);
+  if (value instanceof Set) return Array.from(value);
+  return value;
+}
+function formatLogValue(value) {
+  if (isPrimitive(value)) return value;
+  if (value instanceof Error) return value;
+  try {
+    return JSON.stringify(value, replacer);
+  } catch {
+    return String(value);
+  }
+}
+function wrapLogMethod(fn) {
+  return (options) => {
+    const formattedOptions = Object.fromEntries(
+      Object.entries(options).filter(([key, value]) => {
+        if (key === "error" && !(value instanceof Error)) return false;
+        return true;
+      }).map(([key, value]) => [key, formatLogValue(value)])
+    );
+    return fn(formattedOptions);
+  };
+}
+function wrapPonderAppLogger(rawLogger) {
+  return Object.freeze({
+    ...rawLogger,
+    error: wrapLogMethod(rawLogger.error.bind(rawLogger)),
+    warn: wrapLogMethod(rawLogger.warn.bind(rawLogger)),
+    info: wrapLogMethod(rawLogger.info.bind(rawLogger)),
+    debug: wrapLogMethod(rawLogger.debug.bind(rawLogger)),
+    trace: wrapLogMethod(rawLogger.trace.bind(rawLogger))
+  });
+}
+
+// src/deserialize/ponder-app-context.ts
 var schemaPortNumber = z6.number({ error: "Port must be a number." }).int({ error: "Port must be an integer." }).min(1, { error: "Port must be greater than or equal to 1." }).max(65535, { error: "Port must be less than or equal to 65535." });
+var schemaPonderAppLoggerMethod = z6.function({
+  input: [
+    z6.looseObject({
+      msg: z6.string({ error: "Log message must be a string." }),
+      error: z6.optional(z6.unknown())
+    })
+  ],
+  output: z6.void()
+});
+var schemaRawPonderAppLogger = z6.looseObject({
+  error: schemaPonderAppLoggerMethod,
+  warn: schemaPonderAppLoggerMethod,
+  info: schemaPonderAppLoggerMethod,
+  debug: schemaPonderAppLoggerMethod,
+  trace: schemaPonderAppLoggerMethod
+});
+var schemaPonderAppLogger = schemaRawPonderAppLogger.transform(wrapPonderAppLogger);
 var schemaRawPonderAppContext = z6.object({
   options: z6.object({
     command: z6.enum(PonderAppCommands),
     port: schemaPortNumber
-  })
+  }),
+  logger: schemaRawPonderAppLogger
 });
 var schemaPonderAppContext = z6.object({
   command: z6.enum(PonderAppCommands),
-  localPonderAppUrl: z6.instanceof(URL, { error: "localPonderAppUrl must be a valid URL." })
+  localPonderAppUrl: z6.instanceof(URL, { error: "localPonderAppUrl must be a valid URL." }),
+  logger: schemaPonderAppLogger
 });
 function buildUnvalidatedPonderAppContext(rawPonderAppContext) {
   return {
     command: rawPonderAppContext.options.command,
-    localPonderAppUrl: new URL(`http://localhost:${rawPonderAppContext.options.port}`)
+    localPonderAppUrl: new URL(`http://localhost:${rawPonderAppContext.options.port}`),
+    logger: rawPonderAppContext.logger
   };
 }
 function deserializePonderAppContext(unvalidatedRawPonderAppContext) {