@ar.io/sdk 3.11.0-alpha.7 → 3.11.0-alpha.8

package/lib/types/common/wayfinder/wayfinder.d.ts

@@ -13,9 +13,11 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { WayfinderRouter } from '../../types/wayfinder.js';
+import EventEmitter from 'node:events';
+import { PassThrough, Readable } from 'node:stream';
+import { DataHashProvider, DataVerifier, WayfinderRouter } from '../../types/wayfinder.js';
 import { Logger } from '../logger.js';
-type HttpClientArgs = [string | URL, ...unknown[]];
+type HttpClientArgs = unknown[];
 type HttpClientFunction = (...args: HttpClientArgs) => unknown;
 type WayfinderHttpClient<T extends HttpClientFunction> = T;
 export declare const arnsRegex: RegExp;
@@ -31,6 +33,69 @@ export declare const resolveWayfinderUrl: ({ originalUrl, targetGateway, logger,
     targetGateway: () => Promise<string | URL>;
     logger?: Logger;
 }) => Promise<URL>;
+/**
+ * Wayfinder event emitter with verification events
+ */
+export type WayfinderEvent = {
+    type: 'verification-passed';
+    txId: string;
+} | {
+    type: 'verification-failed';
+    txId: string;
+    error: Error;
+} | {
+    type: 'verification-skipped';
+    originalUrl: string;
+} | {
+    type: 'verification-progress';
+    txId: string;
+    processedBytes: number;
+    totalBytes: number;
+} | {
+    type: 'routing-started';
+    originalUrl: string;
+} | {
+    type: 'routing-succeeded';
+    originalUrl: string;
+    targetGateway: string;
+} | {
+    type: 'routing-failed';
+    originalUrl: string;
+    error: Error;
+} | {
+    type: 'identified-transaction-id';
+    originalUrl: string;
+    targetGateway: string;
+    txId: string;
+};
+export interface WayfinderEventArgs {
+    onVerificationPassed?: (payload: Omit<Extract<WayfinderEvent, {
+        type: 'verification-passed';
+    }>, 'type'>) => void;
+    onVerificationFailed?: (payload: Omit<Extract<WayfinderEvent, {
+        type: 'verification-failed';
+    }>, 'type'>) => void;
+    onVerificationProgress?: (payload: Omit<Extract<WayfinderEvent, {
+        type: 'verification-progress';
+    }>, 'type'>) => void;
+}
+export declare class WayfinderEmitter extends EventEmitter {
+    constructor({ onVerificationPassed, onVerificationFailed, onVerificationProgress, }?: WayfinderEventArgs);
+    emit<E extends WayfinderEvent['type']>(event: E, payload: Omit<Extract<WayfinderEvent, {
+        type: E;
+    }>, 'type'>): boolean;
+    on<E extends WayfinderEvent['type']>(event: E, listener: (payload: Omit<Extract<WayfinderEvent, {
+        type: E;
+    }>, 'type'>) => void): this;
+}
+export declare function tapAndVerifyStream<T extends Readable | ReadableStream>({ originalStream, contentLength, verifyData, txId, emitter, }: {
+    originalStream: T;
+    contentLength: number;
+    verifyData: DataVerifier['verifyData'];
+    txId: string;
+    emitter?: WayfinderEmitter;
+}): T extends Readable ? PassThrough : T;
+export declare function wrapVerifiedResponse(original: Response, newBody: ReadableStream<Uint8Array>, txId: string): Response;
 /**
  * Creates a wrapped http client that supports ar:// protocol
  *
@@ -44,13 +109,18 @@ export declare const resolveWayfinderUrl: ({ originalUrl, targetGateway, logger,
  * @param resolveUrl - the function to construct the redirect url for ar:// requests
  * @returns a wrapped http client that supports ar:// protocol
  */
-export declare const createWayfinderClient: <T extends HttpClientFunction>({ httpClient, resolveUrl, logger, }: {
+export declare const createWayfinderClient: <T extends HttpClientFunction>({ httpClient, resolveUrl, verifyData, emitter, logger, }: {
     httpClient: T;
     resolveUrl: (params: {
         originalUrl: string | URL;
         logger?: Logger;
     }) => Promise<URL>;
+    verifyData?: <T_1 extends Readable | ReadableStream | Buffer>({ data, txId, }: {
+        data: T_1;
+        txId: string;
+    }) => Promise<void>;
     logger?: Logger;
+    emitter?: WayfinderEmitter;
 }) => WayfinderHttpClient<T>;
 /**
  * The main class for the wayfinder
@@ -65,21 +135,31 @@ export declare class Wayfinder<T extends HttpClientFunction> {
      * @example
      * const wayfinder = new Wayfinder({
      *   router: new RandomGatewayRouter({
-     *     gatewaysProvider: new ARIOGatewaysProvider({ ario: ARIO.mainnet() })
+     *     gatewaysProvider: new SimpleCacheGatewaysProvider({
+     *       gatewaysProvider: new NetworkGatewaysProvider({ ario: ARIO.mainnet() }),
+     *       ttlSeconds: 60 * 60 * 24, // 1 day
+     *     }),
      *   }),
      * });
+     *
+     * // Returns a target gateway based on the routing strategy
+     * const targetGateway = await wayfinder.router.getTargetGateway();
      */
     readonly router: WayfinderRouter;
     /**
-     * The http client to use for requests
+     * The native http client used by wayfinder
      *
      * @example
      * const wayfinder = new Wayfinder({
      *   router: new RandomGatewayRouter({
-     *     gatewaysProvider: new ARIOGatewaysProvider({ ario: ARIO.mainnet() })
+     *     gatewaysProvider: new SimpleCacheGatewaysProvider({
+     *       gatewaysProvider: new NetworkGatewaysProvider({ ario: ARIO.mainnet() }),
+     *       ttlSeconds: 60 * 60 * 24, // 1 day
+     *     }),
      *   }),
      *   httpClient: axios,
      * });
+     *
      */
     readonly httpClient: T;
     /**
@@ -88,11 +168,15 @@ export declare class Wayfinder<T extends HttpClientFunction> {
      * @example
      * const wayfinder = new Wayfinder({
      *   router: new RandomGatewayRouter({
-     *     gatewaysProvider: new ARIOGatewaysProvider({ ario: ARIO.mainnet() })
+     *     gatewaysProvider: new SimpleCacheGatewaysProvider({
+     *       gatewaysProvider: new NetworkGatewaysProvider({ ario: ARIO.mainnet() }),
+     *       ttlSeconds: 60 * 60 * 24, // 1 day
+     *     }),
      *   }),
      *   httpClient: axios,
      * });
      *
+     * // returns the redirected URL based on the routing strategy and the original url
      * const redirectUrl = await wayfinder.resolveUrl({ originalUrl: 'ar://example' });
      */
     readonly resolveUrl: (params: {
@@ -105,7 +189,10 @@ export declare class Wayfinder<T extends HttpClientFunction> {
      * @example
      * const { request: wayfind } = new Wayfinder({
      *   router: new RandomGatewayRouter({
-     *     gatewaysProvider: new ARIOGatewaysProvider({ ario: ARIO.mainnet() })
+     *     gatewaysProvider: new SimpleCacheGatewaysProvider({
+     *       gatewaysProvider: new NetworkGatewaysProvider({ ario: ARIO.mainnet() }),
+     *       ttlSeconds: 60 * 60 * 24, // 1 day
+     *     }),
      *   }),
      *   httpClient: axios,
      * });;
@@ -118,10 +205,61 @@ export declare class Wayfinder<T extends HttpClientFunction> {
      * })
      */
     readonly request: WayfinderHttpClient<T>;
-    constructor({ router, httpClient, logger, }: {
-        router: WayfinderRouter;
+    readonly verifyData: DataVerifier['verifyData'];
+    /**
+     * The event emitter for wayfinder that emits verification events.
+     *
+     * const wayfinder = new Wayfinder()
+     *
+     * wayfinder.emitter.on('verification-passed', (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 wayfind('ar://example');
+     */
+    readonly emitter: WayfinderEmitter;
+    constructor({ httpClient, router, logger, verifier, events, }: {
         httpClient: T;
+        router?: WayfinderRouter;
         logger?: Logger;
+        verifier?: DataVerifier;
+        hashProvider?: DataHashProvider;
+        events?: WayfinderEventArgs;
     });
 }
 export {};
+/**
+ *
+ *  type    | complexity | performance | security
+ * ---------|------------|-------------|---------
+ *  hash    | low        | high        | low
+ * ---------|------------|-------------|---------
+ *  data root    | medium       | medium      | low | only L1
+ * ---------|------------|-------------|---------
+ * signature    | medium       | medium      | medium
+ * ---------|------------|-------------|---------
+ *  composite | high       | low         | high
+ * ---------|------------|-------------|---------
+ *
+ *
+ */

package/lib/types/types/wayfinder.d.ts

@@ -13,7 +13,50 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import { Readable } from 'stream';
 export interface WayfinderRouter {
     readonly name: string;
     getTargetGateway: () => Promise<URL>;
 }
+export interface DataVerifier {
+    /**
+     * Verifies the provided data for a given txId
+     *
+     * Depending on the implementation, the hash can be the computed data root of a transaction, the digest of the data, or some other hash of the data.
+     *
+     * The interface is intended to be vague in order to support various degrees of verification.
+     *
+     * @param data - The data to verify
+     * @param txId - The txId of the data
+     * @returns the hash of the data
+     */
+    verifyData: ({ data, txId, }: {
+        data: Buffer | Readable | ReadableStream;
+        txId: string;
+    }) => Promise<void>;
+}
+export interface DataHashProvider {
+    /**
+     * Returns a hash for the provided txId using the specified algorithm.
+     *
+     * @param txId - The txId of the data
+     * @returns the hash of the data
+     */
+    getHash: ({ txId, }: {
+        txId: string;
+    }) => Promise<{
+        hash: string;
+        algorithm: 'sha256';
+    }>;
+}
+export interface DataRootProvider {
+    /**
+     * Returns the data root for the provided txId
+     *
+     * @param txId - The txId of the data
+     * @returns the data root of the data
+     */
+    getDataRoot: ({ txId }: {
+        txId: string;
+    }) => Promise<string>;
+}

package/lib/types/utils/hash.d.ts

@@ -0,0 +1,4 @@
+import { Readable } from 'stream';
+export declare const hashReadableToB64Url: (stream: Readable, algorithm?: string) => Promise<string>;
+export declare const hashReadableStreamToB64Url: (stream: ReadableStream, algorithm?: string) => Promise<string>;
+export declare const hashBufferToB64Url: (buffer: Buffer, algorithm?: string) => string;

package/lib/types/version.d.ts

@@ -13,4 +13,4 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-export declare const version = "3.11.0-alpha.6";
+export declare const version = "3.11.0-alpha.7";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ar.io/sdk",
-  "version": "3.11.0-alpha.7",
+  "version": "3.11.0-alpha.8",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ar-io/ar-io-sdk.git"