@ar.io/wayfinder-core 0.0.3-alpha.6 → 0.0.4-alpha.0

package/README.md

@@ -49,15 +49,48 @@ const wayfinder = new Wayfinder({
       limit: 10,
     }),
   }),
-  // use the fastest pinging strategy to select the fastest gateway for requests
-  routingStrategy: new FastestPingRoutingStrategy({
-    timeoutMs: 1000,
-    probePath: '/ar-io/info',
-  }),
-  // verify the data using the hash of the data against a list of trusted gateways
-  verificationStrategy: new HashVerificationStrategy({
-    trustedGateways: ['https://permagate.io'],
-  }),
+  // routing settings
+  routingSettings: {
+    // use the fastest pinging strategy to select the fastest gateway for requests
+    strategy: new FastestPingRoutingStrategy({
+      timeoutMs: 1000,
+    }),
+    // events
+    events: {
+      onRoutingStarted: (event) => {
+        console.log('Routing started!', event);
+      },
+      onRoutingSkipped: (event) => {
+        console.log('Routing skipped!', event);
+      },
+      onRoutingSucceeded: (event) => {
+        console.log('Routing succeeded!', event);
+      },
+    },
+  },
+  // verification settings
+  verificationSettings: {
+    // enable verification - if false, verification will be skipped for all requests
+    enabled: true,
+    // verify the data using the hash of the data against a list of trusted gateways
+    strategy: new HashVerificationStrategy({
+      trustedGateways: ['https://permagate.io'],
+    }),
+    // strict verification - if true, verification failures will cause requests to fail
+    strict: true,
+    // events
+    events: {
+      onVerificationProgress: (event) => {
+        console.log('Verification progress!', event);
+      },
+      onVerificationSucceeded: (event) => {
+        console.log('Verification succeeded!', event);
+      },
+      onVerificationFailed: (event) => {
+        console.log('Verification failed!', event);
+      },
+    },
+  },
 });
 ```
 
@@ -125,6 +158,8 @@ const gateway = await routingStrategy.selectGateway({
 ### StaticRoutingStrategy
 
 ```javascript
+import { Wayfinder, StaticRoutingStrategy } from '@ar.io/wayfinder-core';
+
 const routingStrategy = new StaticRoutingStrategy({
   gateway: 'https://arweave.net',
 });
@@ -137,6 +172,9 @@ const gateway = await routingStrategy.selectGateway(); // always returns the sam
 Selects gateways in round-robin order. The gateway list is stored in memory and is not persisted across instances.
 
 ```javascript
+import { Wayfinder, NetworkGatewaysProvider, RoundRobinRoutingStrategy } from '@ar.io/wayfinder-core';
+import { ARIO } from '@ar.io/sdk';
+
 const gatewayProvider = new NetworkGatewaysProvider({
   ario: ARIO.mainnet(),
   sortBy: 'operatorStake',
@@ -158,6 +196,8 @@ const gateway = await routingStrategy.selectGateway(); // returns the next gatew
 Selects the fastest gateway based simple HEAD request to the specified route.
 
 ```javascript
+import { Wayfinder, FastestPingRoutingStrategy } from '@ar.io/wayfinder-core';
+
 const routingStrategy = new FastestPingRoutingStrategy({
   timeoutMs: 1000,
 });
@@ -186,9 +226,11 @@ Verifies data integrity using SHA-256 hash comparison. This is the default verif
 import { Wayfinder, HashVerificationStrategy } from '@ar.io/wayfinder-core';
 
 const wayfinder = new Wayfinder({
-  verificationStrategy: new HashVerificationStrategy({
-    trustedGateways: ['https://permagate.io'],
-  }),
+  verificationSettings: {
+    strategy: new HashVerificationStrategy({
+      trustedGateways: ['https://permagate.io'],
+    }),
+  },
 });
 ```
 
@@ -200,9 +242,11 @@ Verifies data integrity using Arweave by computing the data root for the transac
 import { Wayfinder, DataRootVerificationStrategy } from '@ar.io/wayfinder-core';
 
 const wayfinder = new Wayfinder({
-  verificationStrategy: new DataRootVerificationStrategy({
-    trustedGateways: ['https://permagate.io'],
-  }),
+  verificationSettings: {
+    strategy: new DataRootVerificationStrategy({
+      trustedGateways: ['https://permagate.io'],
+    }),
+  },
 });
 ```
 
@@ -214,33 +258,50 @@ Verifies signatures of Arweave transactions and data items. Headers are retrieve
 import { Wayfinder, SignatureVerificationStrategy } from '@ar-io/sdk';
 
 const wayfinder = new Wayfinder({
-  verificationStrategy: new SignatureVerificationStrategy({
-    trustedGateways: ['https://permagate.io'],
-  }),
+  verificationSettings: {
+    strategy: new SignatureVerificationStrategy({
+      trustedGateways: ['https://permagate.io'],
+    }),
+  },
 });
 ```
 
 ## Monitoring and Events
 
-Wayfinder emits events during the routing and verification process, allowing you to monitor its operation.
+Wayfinder emits events during the routing and verification process, allowing you to monitor its operation. You can provide these events to the Wayfinder constructor or use the event emitter directly.
 
 ```javascript
 const wayfinder = new Wayfinder({
-  events: {
-    onVerificationPassed: (event) => {
-      console.log(`Verification passed for transaction: ${event.txId}`);
-    },
-    onVerificationFailed: (event) => {
-      console.error(
-        `Verification failed for transaction: ${event.txId}`,
-        event.error,
-      );
+  routingSettings: {
+    events: {
+      onRoutingStarted: (event) => {
+        console.log('Routing started!', event);
+      },
+      onRoutingSkipped: (event) => {
+        console.log('Routing skipped!', event);
+      },
+      onRoutingSucceeded: (event) => {
+        console.log('Routing succeeded!', event);
+      },
     },
-    onVerificationProgress: (event) => {
-      const percentage = (event.processedBytes / event.totalBytes) * 100;
-      console.log(
-        `Verification progress for ${event.txId}: ${percentage.toFixed(2)}%`,
-      );
+  },
+  verificationSettings: {
+    events: {
+      onVerificationSucceeded: (event) => {
+        console.log(`Verification passed for transaction: ${event.txId}`);
+      },
+      onVerificationFailed: (event) => {
+        console.error(
+          `Verification failed for transaction: ${event.txId}`,
+          event.error,
+        );
+      },
+      onVerificationProgress: (event) => {
+        const percentage = (event.processedBytes / event.totalBytes) * 100;
+        console.log(
+          `Verification progress for ${event.txId}: ${percentage.toFixed(2)}%`,
+        );
+      },
     },
   },
 });
@@ -253,12 +314,26 @@ wayfinder.emitter.on('routing-succeeded', (event) => {
 wayfinder.emitter.on('routing-failed', (event) => {
   console.error(`Routing failed: ${event.error.message}`);
 });
+
+wayfinder.emitter.on('verification-progress', (event) => {
+  console.log(`Verification progress: ${event.progress}%`);
+});
+
+wayfinder.emitter.on('verification-succeeded', (event) => {
+  console.log(`Verification succeeded: ${event.txId}`);
+});
+
+wayfinder.emitter.on('verification-failed', (event) => {
+  console.error(`Verification failed: ${event.error.message}`);
+});
 ```
 
 ## Advanced Usage
 
 ### Custom URL Resolution
 
+Returns the resolved URL for a given ar:// URL. This is useful for debugging and for users who want to know the target gateway for a given ar:// URL.
+
 ```javascript
 // Get the resolved URL without making a request
 const redirectUrl = await wayfinder.resolveUrl({
@@ -267,27 +342,6 @@ const redirectUrl = await wayfinder.resolveUrl({
 console.log(`This request would be routed to: ${redirectUrl}`);
 ```
 
-### Using With Different HTTP Clients
-
-By default, Wayfinder uses native `fetch` for HTTP requests. You can also use other HTTP clients like `axios` or `node-fetch`. When making a request, Wayfinder will use the HTTP client you provide and any additional configuration you provide.
-
-```javascript
-import axios from 'axios';
-
-// create a custom axios instance
-const axios = axios.create({
-  timeout: 10000,
-});
-const wayfinderAxios = new Wayfinder({ httpClient: axios });
-
-// add custom headers on the request
-const response = await wayfinderAxios.request('ar://example', {
-  headers: {
-    'X-Custom-Header': 'test',
-  },
-});
-```
-
 ## Request Flow
 
 The following sequence diagram illustrates how Wayfinder processes requests:

package/dist/utils/hash.js

@@ -14,7 +14,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import * as crypto from 'crypto';
+import { createHash } from 'crypto';
 import { defaultLogger } from '../wayfinder.js';
 import { toB64Url } from './base64.js';
 export function isAsyncIterable(obj) {
@@ -48,7 +48,7 @@ export async function hashDataStreamToB64Url({ stream, algorithm = 'sha256', log
         const asyncIterable = isAsyncIterable(stream)
             ? stream
             : readableStreamToAsyncIterable(stream);
-        const hash = crypto.createHash(algorithm);
+        const hash = createHash(algorithm);
         let bytesProcessed = 0;
         for await (const chunk of asyncIterable) {
             hash.update(chunk);

package/dist/wayfinder.d.ts

@@ -78,13 +78,22 @@ export type WayfinderEvent = {
         txId: string;
     };
 };
-export interface WayfinderEventArgs {
+export interface WayfinderRoutingEventArgs {
+    onRoutingStarted?: (payload: WayfinderEvent['routing-started']) => void;
+    onRoutingSkipped?: (payload: WayfinderEvent['routing-skipped']) => void;
+    onRoutingSucceeded?: (payload: WayfinderEvent['routing-succeeded']) => void;
+}
+export interface WayfinderVerificationEventArgs {
     onVerificationSucceeded?: (payload: WayfinderEvent['verification-succeeded']) => void;
     onVerificationFailed?: (payload: WayfinderEvent['verification-failed']) => void;
     onVerificationProgress?: (payload: WayfinderEvent['verification-progress']) => void;
 }
+export interface WayfinderEventArgs {
+    verification?: WayfinderVerificationEventArgs;
+    routing?: WayfinderRoutingEventArgs;
+}
 export declare class WayfinderEmitter extends EventEmitter<WayfinderEvent> {
-    constructor({ onVerificationSucceeded, onVerificationFailed, onVerificationProgress, }?: WayfinderEventArgs);
+    constructor({ verification, routing }?: WayfinderEventArgs);
 }
 export declare function tapAndVerifyReadableStream({ originalStream, contentLength, verifyData, txId, emitter, strict, }: {
     originalStream: ReadableStream;
@@ -109,7 +118,7 @@ export declare function sandboxFromId(id: string): string;
  * @param resolveUrl - the function to construct the redirect url for ar:// requests
  * @returns a wrapped fetch function that supports ar:// protocol and always returns Response
  */
-export declare const createWayfinderClient: ({ getGateways, resolveUrl, verifyData, selectGateway, emitter, logger, strict, }: {
+export declare const wayfinderRequest: ({ getGateways, resolveUrl, verifyData, selectGateway, emitter, logger, strict, }: {
     getGateways: GatewaysProvider["getGateways"];
     selectGateway: RoutingStrategy["selectGateway"];
     resolveUrl: (params: {
@@ -132,30 +141,47 @@ export interface WayfinderOptions {
      */
     logger?: Logger;
     /**
-     * The gateways provider to use for routing requests
+     * The gateways provider to use for routing requests.
      */
     gatewaysProvider: GatewaysProvider;
     /**
-     * The routing strategy to use for selecting gateways
-     * @default FastestPingRoutingStrategy with timeoutMs=1000
-     */
-    routingStrategy?: RoutingStrategy;
-    /**
-     * The verification strategy to use for verifying data
-     * @default HashVerificationStrategy with TrustedGatewaysHashProvider
+     * The verification settings to use for verifying data
      */
-    verificationStrategy?: VerificationStrategy;
-    /**
-     * Event handlers for verification events
-     */
-    events?: WayfinderEventArgs;
+    verificationSettings?: {
+        /**
+         * Whether verification is enabled. If false, verification will be skipped for all requests.
+         * @default true
+         */
+        enabled?: boolean;
+        /**
+         * Whether verification should be strict (blocking)
+         * If true, verification failures will cause requests to fail
+         * If false, verification will be performed asynchronously with events emitted
+         * @default false
+         */
+        strict?: boolean;
+        /**
+         * The events to use for verification
+         */
+        events?: WayfinderVerificationEventArgs;
+        /**
+         * The verification strategy to use for verifying data
+         */
+        strategy?: VerificationStrategy;
+    };
     /**
-     * Whether verification should be strict (blocking)
-     * If true, verification failures will cause requests to fail
-     * If false, verification will be performed asynchronously
-     * @default false
+     * The routing settings to use for routing requests
      */
-    strict?: boolean;
+    routingSettings?: {
+        /**
+         * The routing strategy to use for routing requests
+         */
+        strategy?: RoutingStrategy;
+        /**
+         * The events to use for routing requests
+         */
+        events?: WayfinderRoutingEventArgs;
+    };
 }
 /**
  * The main class for the wayfinder
@@ -175,15 +201,12 @@ export declare class Wayfinder {
     readonly gatewaysProvider: GatewaysProvider;
     /**
      * The routing strategy to use when routing requests.
-     *
-     * @example
-     * const wayfinder = new Wayfinder({
-     *   strategy: new FastestPingStrategy({
-     *     timeoutMs: 1000,
-     *   }),
-     * });
      */
     readonly routingStrategy: RoutingStrategy;
+    /**
+     * The verification strategy to use when verifying data.
+     */
+    readonly verificationStrategy: VerificationStrategy;
     /**
      * A helper function that resolves the redirect url for ar:// requests to a target gateway.
      *
@@ -245,18 +268,12 @@ export declare class Wayfinder {
      * });
      */
     readonly verifyData: VerificationStrategy['verifyData'];
-    /**
-     * Whether verification should be strict (blocking) or not.
-     * If true, verification failures will cause requests to fail.
-     * If false, verification will be performed asynchronously and failures will only emit events.
-     */
-    readonly strict: boolean;
     /**
      * The logger used by this Wayfinder instance
      */
     readonly logger: Logger;
     /**
-     * The event emitter for wayfinder that emits verification events.
+     * The event emitter for wayfinder that emits routing and verification events.
      *
      * const wayfinder = new Wayfinder()
      *
@@ -271,17 +288,40 @@ export declare class Wayfinder {
      * or implement the events interface and pass it in, using callback functions
      *
      * const wayfinder = new Wayfinder({
-     *   events: {
-     *     onVerificationPassed: (event) => {
-     *       console.log('Verification passed!', event);
-     *     },
-     *     onVerificationFailed: (event) => {
+     *   verificationSettings: {
+     *     strategy: new HashVerificationStrategy({
+     *       trustedGateways: [new URL('https://permagate.io')],
+     *     }),
+     *     events: {
+     *       onVerificationProgress: (event) => {
+     *         console.log('Verification progress!', event);
+     *       },
+     *       onVerificationSucceeded: (event) => {
+     *         console.log('Verification passed!', event);
+     *       },
+     *       onVerificationFailed: (event) => {
      *       console.log('Verification failed!', event);
      *     },
      *     onVerificationProgress: (event) => {
      *       console.log('Verification progress!', event);
      *     },
      *   }
+     *   routingSettings: {
+     *     strategy: new FastestPingRoutingStrategy({
+     *       timeoutMs: 1000,
+     *     }),
+     *     events: {
+     *       onRoutingStarted: (event) => {
+     *         console.log('Routing started!', event);
+     *       },
+     *       onRoutingSkipped: (event) => {
+     *         console.log('Routing skipped!', event);
+     *       },
+     *       onRoutingSucceeded: (event) => {
+     *         console.log('Routing succeeded!', event);
+     *       },
+     *     },
+     *   }
      * })
      *
      * const response = await wayfinder.request('ar://example');
@@ -291,7 +331,7 @@ export declare class Wayfinder {
      * The constructor for the wayfinder
      * @param options - Wayfinder configuration options
      */
-    constructor({ logger, gatewaysProvider, routingStrategy, verificationStrategy, events, strict, }: WayfinderOptions);
+    constructor({ logger, gatewaysProvider, verificationSettings, routingSettings, }: WayfinderOptions);
 }
 export {};
 //# sourceMappingURL=wayfinder.d.ts.map

package/dist/wayfinder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wayfinder.d.ts","sourceRoot":"","sources":["../src/wayfinder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"wayfinder.d.ts","sourceRoot":"","sources":["../src/wayfinder.ts"],"names":[],"mappings":"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"}

package/dist/wayfinder.js

@@ -76,16 +76,29 @@ export const resolveWayfinderUrl = ({ originalUrl, selectedGateway, logger, }) =
     return new URL(originalUrl);
 };
 export class WayfinderEmitter extends EventEmitter {
-    constructor({ onVerificationSucceeded, onVerificationFailed, onVerificationProgress, } = {}) {
+    constructor({ verification, routing } = {}) {
         super();
-        if (onVerificationSucceeded) {
-            this.on('verification-succeeded', onVerificationSucceeded);
-        }
-        if (onVerificationFailed) {
-            this.on('verification-failed', onVerificationFailed);
+        if (verification) {
+            if (verification.onVerificationSucceeded) {
+                this.on('verification-succeeded', verification.onVerificationSucceeded);
+            }
+            if (verification.onVerificationFailed) {
+                this.on('verification-failed', verification.onVerificationFailed);
+            }
+            if (verification.onVerificationProgress) {
+                this.on('verification-progress', verification.onVerificationProgress);
+            }
         }
-        if (onVerificationProgress) {
-            this.on('verification-progress', onVerificationProgress);
+        if (routing) {
+            if (routing.onRoutingStarted) {
+                this.on('routing-started', routing.onRoutingStarted);
+            }
+            if (routing.onRoutingSkipped) {
+                this.on('routing-skipped', routing.onRoutingSkipped);
+            }
+            if (routing.onRoutingSucceeded) {
+                this.on('routing-succeeded', routing.onRoutingSucceeded);
+            }
         }
     }
 }
@@ -185,10 +198,14 @@ export function sandboxFromId(id) {
  * @param resolveUrl - the function to construct the redirect url for ar:// requests
  * @returns a wrapped fetch function that supports ar:// protocol and always returns Response
  */
-export const createWayfinderClient = ({ getGateways, resolveUrl, verifyData, selectGateway, emitter = new WayfinderEmitter(), logger = defaultLogger, strict = false, }) => {
+export const wayfinderRequest = ({ getGateways, resolveUrl, verifyData, selectGateway, emitter = new WayfinderEmitter(), logger = defaultLogger, strict = false, }) => {
     return async (input, init) => {
-        if (typeof input !== 'string' && !(input instanceof URL)) {
-            logger?.debug('URL is not a string, skipping routing', {
+        const url = input instanceof URL ? input.toString() : input.toString();
+        console.log('URL', {
+            url,
+        });
+        if (!url.toString().startsWith('ar://')) {
+            logger?.debug('URL is not a wayfinder url, skipping routing', {
                 input,
             });
             emitter?.emit('routing-skipped', {
@@ -196,9 +213,8 @@ export const createWayfinderClient = ({ getGateways, resolveUrl, verifyData, sel
             });
             return fetch(input, init);
         }
-        const url = input.toString();
         emitter?.emit('routing-started', {
-            originalUrl: url,
+            originalUrl: input.toString(),
         });
         const maxRetries = 3;
         const retryDelay = 1000;
@@ -207,8 +223,8 @@ export const createWayfinderClient = ({ getGateways, resolveUrl, verifyData, sel
                 // select the target gateway
                 const selectedGateway = await selectGateway({
                     gateways: await getGateways(),
-                    path: input instanceof URL ? input.pathname.split('/')[1] : '',
-                    subdomain: input instanceof URL ? input.hostname.split('.')[0] : '',
+                    path: url.split('/').slice(1).join('/'), // everything after the first /
+                    subdomain: '',
                 });
                 logger?.debug('Selected gateway', {
                     originalUrl: url,
@@ -216,7 +232,7 @@ export const createWayfinderClient = ({ getGateways, resolveUrl, verifyData, sel
                 });
                 // route the request to the target gateway
                 const redirectUrl = resolveUrl({
-                    originalUrl: url,
+                    originalUrl: url.toString(),
                     selectedGateway,
                     logger,
                 });
@@ -332,15 +348,12 @@ export class Wayfinder {
     gatewaysProvider;
     /**
      * The routing strategy to use when routing requests.
-     *
-     * @example
-     * const wayfinder = new Wayfinder({
-     *   strategy: new FastestPingStrategy({
-     *     timeoutMs: 1000,
-     *   }),
-     * });
      */
     routingStrategy;
+    /**
+     * The verification strategy to use when verifying data.
+     */
+    verificationStrategy;
     /**
      * A helper function that resolves the redirect url for ar:// requests to a target gateway.
      *
@@ -399,18 +412,12 @@ export class Wayfinder {
      * });
      */
     verifyData;
-    /**
-     * Whether verification should be strict (blocking) or not.
-     * If true, verification failures will cause requests to fail.
-     * If false, verification will be performed asynchronously and failures will only emit events.
-     */
-    strict;
     /**
      * The logger used by this Wayfinder instance
      */
     logger;
     /**
-     * The event emitter for wayfinder that emits verification events.
+     * The event emitter for wayfinder that emits routing and verification events.
      *
      * const wayfinder = new Wayfinder()
      *
@@ -425,17 +432,40 @@ export class Wayfinder {
      * or implement the events interface and pass it in, using callback functions
      *
      * const wayfinder = new Wayfinder({
-     *   events: {
-     *     onVerificationPassed: (event) => {
-     *       console.log('Verification passed!', event);
-     *     },
-     *     onVerificationFailed: (event) => {
+     *   verificationSettings: {
+     *     strategy: new HashVerificationStrategy({
+     *       trustedGateways: [new URL('https://permagate.io')],
+     *     }),
+     *     events: {
+     *       onVerificationProgress: (event) => {
+     *         console.log('Verification progress!', event);
+     *       },
+     *       onVerificationSucceeded: (event) => {
+     *         console.log('Verification passed!', event);
+     *       },
+     *       onVerificationFailed: (event) => {
      *       console.log('Verification failed!', event);
      *     },
      *     onVerificationProgress: (event) => {
      *       console.log('Verification progress!', event);
      *     },
      *   }
+     *   routingSettings: {
+     *     strategy: new FastestPingRoutingStrategy({
+     *       timeoutMs: 1000,
+     *     }),
+     *     events: {
+     *       onRoutingStarted: (event) => {
+     *         console.log('Routing started!', event);
+     *       },
+     *       onRoutingSkipped: (event) => {
+     *         console.log('Routing skipped!', event);
+     *       },
+     *       onRoutingSucceeded: (event) => {
+     *         console.log('Routing succeeded!', event);
+     *       },
+     *     },
+     *   }
      * })
      *
      * const response = await wayfinder.request('ar://example');
@@ -445,29 +475,58 @@ export class Wayfinder {
      * The constructor for the wayfinder
      * @param options - Wayfinder configuration options
      */
-    constructor({ logger = defaultLogger, gatewaysProvider, routingStrategy = new FastestPingRoutingStrategy({
-        timeoutMs: 1000,
-        logger,
-    }), verificationStrategy = new HashVerificationStrategy({
-        trustedGateways: [new URL('https://permagate.io')],
-    }), events = {
-        onVerificationSucceeded: (event) => {
-            logger.debug('Verification passed!', event);
-        },
-        onVerificationFailed: (event) => {
-            logger.error('Verification failed!', event);
+    constructor({ logger = defaultLogger, gatewaysProvider, verificationSettings = {
+        enabled: true,
+        strict: false,
+        strategy: new HashVerificationStrategy({
+            trustedGateways: [new URL('https://permagate.io')],
+        }),
+        events: {
+            onVerificationProgress: (event) => {
+                logger.debug('Verification progress!', event);
+            },
+            onVerificationSucceeded: (event) => {
+                logger.debug('Verification succeeded!', event);
+            },
+            onVerificationFailed: (event) => {
+                logger.error('Verification failed!', event);
+            },
         },
-        onVerificationProgress: (event) => {
-            logger.debug('Verification progress!', event);
+    }, routingSettings = {
+        strategy: new FastestPingRoutingStrategy({
+            timeoutMs: 1000,
+            logger,
+        }),
+        events: {
+            onRoutingStarted: (event) => {
+                logger.debug('Routing started!', event);
+            },
+            onRoutingSkipped: (event) => {
+                logger.debug('Routing skipped!', event);
+            },
+            onRoutingSucceeded: (event) => {
+                logger.debug('Routing succeeded!', event);
+            },
         },
-    }, strict = false, }) {
+    }, }) {
         this.logger = logger;
-        this.routingStrategy = routingStrategy;
+        this.routingStrategy =
+            routingSettings.strategy ??
+                new FastestPingRoutingStrategy({
+                    timeoutMs: 1000,
+                    logger,
+                });
+        this.verificationStrategy =
+            verificationSettings.strategy ??
+                new HashVerificationStrategy({
+                    trustedGateways: [new URL('https://permagate.io')],
+                });
         this.gatewaysProvider = gatewaysProvider;
-        this.emitter = new WayfinderEmitter(events);
-        this.verifyData =
-            verificationStrategy.verifyData.bind(verificationStrategy);
-        this.strict = strict;
+        this.emitter = new WayfinderEmitter({
+            verification: verificationSettings.events,
+            routing: routingSettings.events,
+        });
+        this.verifyData = this.verificationStrategy.verifyData.bind(this.verificationStrategy);
         // top level function to easily resolve wayfinder urls using the routing strategy and gateways provider
         this.resolveUrl = async ({ originalUrl, logger = this.logger }) => {
             const selectedGateway = await this.routingStrategy.selectGateway({
@@ -479,16 +538,16 @@ export class Wayfinder {
                 logger,
             });
         };
-        // create a wayfinder client with the routing strategy and gateways provider
-        this.request = createWayfinderClient({
+        // create a wayfinder request function with the routing strategy and gateways provider
+        this.request = wayfinderRequest({
             getGateways: this.gatewaysProvider.getGateways.bind(this.gatewaysProvider),
+            verifyData: this.verifyData,
             selectGateway: this.routingStrategy.selectGateway.bind(this.routingStrategy),
             resolveUrl: resolveWayfinderUrl,
-            verifyData: this.verifyData,
             emitter: this.emitter,
             logger: this.logger,
-            strict,
+            strict: verificationSettings.strict,
         });
-        logger.debug(`Wayfinder initialized with ${routingStrategy.constructor.name} routing strategy`);
+        logger.debug(`Wayfinder initialized with ${this.routingStrategy.constructor.name} routing strategy`);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ar.io/wayfinder-core",
-  "version": "0.0.3-alpha.6",
+  "version": "0.0.4-alpha.0",
   "description": "WayFinder core library for intelligently routing to optimal AR.IO gateways",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -41,7 +41,7 @@
     "build": "npm run clean && tsc",
     "clean": "rimraf dist",
     "test": "npm run test:unit",
-    "test:unit": "c8 node --import=../../register.mjs --test --enable-source-maps --trace-warnings 'src/**/*.test.ts'",
+    "test:unit": "c8 tsx --enable-source-maps --trace-uncaught --trace-warnings --trace-deprecation src/**/*.test.ts",
     "lint:fix": "biome check --write --unsafe",
     "lint:check": "biome check --unsafe",
     "format:fix": "biome format --write",
@@ -59,6 +59,7 @@
   },
   "devDependencies": {
     "@ar.io/sdk": "^3.13.0",
-    "@types/node": "^24.0.0"
+    "@types/node": "^24.0.0",
+    "tsx": "^4.20.3"
   }
 }