@ar.io/wayfinder-core 0.0.1

package/dist/wayfinder.d.ts

@@ -0,0 +1,301 @@
+/**
+ * WayFinder
+ * Copyright (C) 2022-2025 Permanent Data Solutions, Inc. All Rights Reserved.
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+import { EventEmitter } from 'eventemitter3';
+import { DataVerificationStrategy, GatewaysProvider, RoutingStrategy } from '../types/wayfinder.js';
+type WayfinderHttpClient = typeof fetch;
+/**
+ * Simple logger interface that Wayfinder will use
+ * This allows users to provide their own logger implementation
+ */
+export interface Logger {
+    debug: (message: string, ...args: any[]) => void;
+    info: (message: string, ...args: any[]) => void;
+    warn: (message: string, ...args: any[]) => void;
+    error: (message: string, ...args: any[]) => void;
+}
+/**
+ * Default console logger implementation
+ */
+export declare const defaultLogger: Logger;
+export declare const arnsRegex: RegExp;
+export declare const txIdRegex: RegExp;
+/**
+ * Core function that converts a wayfinder url to the proper ar-io gateway URL
+ * @param originalUrl - the wayfinder url to resolve
+ * @param selectedGateway - the target gateway to resolve the url against
+ * @returns the resolved url that can be used to make a request
+ */
+export declare const resolveWayfinderUrl: ({ originalUrl, selectedGateway, logger, }: {
+    originalUrl: string;
+    selectedGateway: URL;
+    logger?: Logger;
+}) => URL;
+/**
+ * Wayfinder event emitter with verification events
+ */
+export type WayfinderEvent = {
+    'verification-succeeded': {
+        txId: string;
+    };
+    'verification-failed': Error;
+    'verification-skipped': {
+        originalUrl: string;
+    };
+    'verification-progress': {
+        txId: string;
+        processedBytes: number;
+        totalBytes: number;
+    };
+    'routing-started': {
+        originalUrl: string;
+    };
+    'routing-skipped': {
+        originalUrl: string;
+    };
+    'routing-succeeded': {
+        originalUrl: string;
+        selectedGateway: string;
+        redirectUrl: string;
+    };
+    'routing-failed': Error;
+    'identified-transaction-id': {
+        originalUrl: string;
+        selectedGateway: string;
+        txId: string;
+    };
+};
+export interface WayfinderEventArgs {
+    onVerificationSucceeded?: (payload: WayfinderEvent['verification-succeeded']) => void;
+    onVerificationFailed?: (payload: WayfinderEvent['verification-failed']) => void;
+    onVerificationProgress?: (payload: WayfinderEvent['verification-progress']) => void;
+}
+export declare class WayfinderEmitter extends EventEmitter<WayfinderEvent> {
+    constructor({ onVerificationSucceeded, onVerificationFailed, onVerificationProgress, }?: WayfinderEventArgs);
+}
+export declare function tapAndVerifyReadableStream({ originalStream, contentLength, verifyData, txId, emitter, strict, }: {
+    originalStream: ReadableStream;
+    contentLength: number;
+    verifyData: DataVerificationStrategy['verifyData'];
+    txId: string;
+    emitter?: WayfinderEmitter;
+    strict?: boolean;
+}): ReadableStream;
+/**
+ * Gets the sandbox hash for a given transaction id
+ */
+export declare function sandboxFromId(id: string): string;
+/**
+ * Creates a wrapped fetch function that supports ar:// protocol
+ *
+ * This function leverages a Proxy to intercept calls to fetch
+ * and redirects them to the target gateway using the resolveUrl function.
+ *
+ * Any URLs provided that are not wayfinder urls will be passed directly to fetch.
+ *
+ * @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: ({ resolveUrl, verifyData, selectGateway, emitter, logger, strict, }: {
+    selectGateway: () => Promise<URL>;
+    resolveUrl: (params: {
+        originalUrl: string;
+        selectedGateway: URL;
+        logger?: Logger;
+    }) => URL;
+    verifyData?: DataVerificationStrategy["verifyData"];
+    logger?: Logger;
+    emitter?: WayfinderEmitter;
+    strict?: boolean;
+}) => (input: URL | RequestInfo, init?: RequestInit) => Promise<Response>;
+/**
+ * Configuration options for the Wayfinder
+ */
+export interface WayfinderOptions {
+    /**
+     * Logger to use for logging
+     * @default defaultLogger (standard console logger)
+     */
+    logger?: Logger;
+    /**
+     * 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
+     */
+    verificationStrategy?: DataVerificationStrategy;
+    /**
+     * Event handlers for verification events
+     */
+    events?: WayfinderEventArgs;
+    /**
+     * Whether verification should be strict (blocking)
+     * If true, verification failures will cause requests to fail
+     * If false, verification will be performed asynchronously
+     * @default false
+     */
+    strict?: boolean;
+}
+/**
+ * The main class for the wayfinder
+ */
+export declare class Wayfinder {
+    /**
+     * The gateways provider is responsible for providing the list of gateways to use for routing requests.
+     *
+     * @example
+     * const wayfinder = new Wayfinder({
+     *   gatewaysProvider: new SimpleCacheGatewaysProvider({
+     *     gatewaysProvider: new NetworkGatewaysProvider({ ario: ARIO.mainnet() }),
+     *     ttlSeconds: 60 * 60 * 24, // 1 day
+     *   }),
+     * });
+     */
+    readonly gatewaysProvider: GatewaysProvider;
+    /**
+     * The routing strategy to use when routing requests.
+     *
+     * @example
+     * const wayfinder = new Wayfinder({
+     *   strategy: new FastestPingStrategy({
+     *     timeoutMs: 1000,
+     *   }),
+     * });
+     */
+    readonly routingStrategy: RoutingStrategy;
+    /**
+     * A helper function that resolves the redirect url for ar:// requests to a target gateway.
+     *
+     * Note: no verification is done when resolving an ar://<path> url to a wayfinder route.
+     * In order to verify the data, you must use the `request` function or request the data and
+     * verify it yourself via the `verifyData` function.
+     *
+     * @example
+     * const { resolveUrl } = new Wayfinder();
+     *
+     * // returns the redirected URL based on the routing strategy and the original url
+     * const redirectUrl = await resolveUrl({ originalUrl: 'ar://example' });
+     *
+     * window.open(redirectUrl.toString(), '_blank');
+     */
+    readonly resolveUrl: (params: {
+        originalUrl: string;
+        logger?: Logger;
+    }) => Promise<URL>;
+    /**
+     * A wrapped fetch function that supports ar:// protocol. If a verification strategy is provided,
+     * the request will be verified and events will be emitted as the request is processed.
+     *
+     * @example
+     * const wayfinder = new Wayfinder({
+     *   verificationStrategy: new HashVerificationStrategy({
+     *     trustedHashProvider: new TrustedGatewaysHashProvider({
+     *       gatewaysProvider: new StaticGatewaysProvider({
+     *         gateways: ['https://permagate.io'],
+     *       }),
+     *     }),
+     *   }),
+     * })
+     *
+     * // request an arns name
+     * const response = await wayfinder.request('ar://ardrive')
+     *
+     * // request a transaction id
+     * const response = await wayfinder.request('ar://1234567890')
+     *
+     * // Set strict mode to true to make verification blocking
+     * const wayfinder = new Wayfinder({
+     *   strict: true,
+     * });
+     *
+     * // This will throw an error if verification fails
+     * try {
+     *   const response = await wayfinder.request('ar://1234567890');
+     * } catch (error) {
+     *   console.error('Verification failed', error);
+     * }
+     */
+    readonly request: WayfinderHttpClient;
+    /**
+     * The function that verifies the data hash for a given transaction id.
+     *
+     * @example
+     * const wayfinder = new Wayfinder({
+     *   verifyData: (data, txId) => {
+     *     // some custom verification logic
+     *     return true;
+     *   },
+     * });
+     */
+    readonly verifyData: DataVerificationStrategy['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.
+     *
+     * const wayfinder = new Wayfinder()
+     *
+     * wayfinder.emitter.on('verification-succeeded', (event) => {
+     *   console.log('Verification passed!', event);
+     * })
+     *
+     * wayfinder.emitter.on('verification-failed', (event) => {
+     *   console.log('Verification failed!', event);
+     * })
+     *
+     * 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) => {
+     *       console.log('Verification failed!', event);
+     *     },
+     *     onVerificationProgress: (event) => {
+     *       console.log('Verification progress!', event);
+     *     },
+     *   }
+     * })
+     *
+     * const response = await wayfinder.request('ar://example');
+     */
+    readonly emitter: WayfinderEmitter;
+    /**
+     * The constructor for the wayfinder
+     * @param options - Wayfinder configuration options
+     */
+    constructor({ logger, gatewaysProvider, routingStrategy, verificationStrategy, events, strict, }: WayfinderOptions);
+}
+export {};
+//# sourceMappingURL=wayfinder.d.ts.map

package/dist/wayfinder.d.ts.map

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