@ar.io/sdk 3.13.0-beta.1 → 3.14.0-alpha.1

package/lib/types/common/wayfinder/routing/strategies/random.d.ts

@@ -1,21 +0,0 @@
-/**
- * Copyright (C) 2022-2024 Permanent Data Solutions, Inc.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-import { RoutingStrategy } from '../../../../types/wayfinder.js';
-export declare class RandomRoutingStrategy implements RoutingStrategy {
-    selectGateway({ gateways }: {
-        gateways: URL[];
-    }): Promise<URL>;
-}

package/lib/types/common/wayfinder/routing/strategies/round-robin.d.ts

@@ -1,29 +0,0 @@
-/**
- * Copyright (C) 2022-2024 Permanent Data Solutions, Inc.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-import { Logger } from '../../../../common/logger.js';
-import { RoutingStrategy } from '../../../../types/wayfinder.js';
-export declare class RoundRobinRoutingStrategy implements RoutingStrategy {
-    private gateways;
-    private currentIndex;
-    private logger;
-    constructor({ gateways, logger, }: {
-        gateways: URL[];
-        logger?: Logger;
-    });
-    selectGateway({ gateways, }?: {
-        gateways?: URL[];
-    }): Promise<URL>;
-}

package/lib/types/common/wayfinder/routing/strategies/static.d.ts

@@ -1,29 +0,0 @@
-/**
- * Copyright (C) 2022-2024 Permanent Data Solutions, Inc.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-import { RoutingStrategy } from '../../../../types/wayfinder.js';
-import { Logger } from '../../../logger.js';
-export declare class StaticRoutingStrategy implements RoutingStrategy {
-    readonly name = "static";
-    private gateway;
-    private logger;
-    constructor({ gateway, logger, }: {
-        gateway: string;
-        logger?: Logger;
-    });
-    selectGateway({ gateways, }?: {
-        gateways?: URL[];
-    }): Promise<URL>;
-}

package/lib/types/common/wayfinder/verification/strategies/data-root-verifier.d.ts

@@ -1,27 +0,0 @@
-import { DataRootProvider, DataStream, DataVerificationStrategy } from '../../../../types/wayfinder.js';
-export declare const convertDataStreamToDataRoot: ({ dataStream, }: {
-    dataStream: DataStream;
-}) => Promise<string>;
-export declare class DataRootVerificationStrategy implements DataVerificationStrategy {
-    private readonly trustedDataRootProvider;
-    constructor({ trustedDataRootProvider, }: {
-        trustedDataRootProvider: DataRootProvider;
-    });
-    verifyData({ data, txId, }: {
-        data: DataStream;
-        txId: string;
-    }): Promise<void>;
-}
-/**
- * - when you get a signature of a data item, you can only verify the owner
- * - you still need to verify it's going back to the bundle, unpack it, and verify the data item exists at the offset
- * - you need to the location of the chunks for the data item, and prove it's in the chunk and then prove the data root of the bundle, then you have fully verified the data verifier
- * - how to prove the data item is on arweave - verify the merkle hash that the chunks for the data item, fit within the expected tree of the parent bundle
- *
- * Composite verifier - you'll want to be very efficient with streams
- * - hash verifier
- * - parent chunks verifier --> for any range of data within a single transaction, tell me that it's correct
- * - signature verifier
- * - offset verifier
- * - data item verifier
- */

package/lib/types/common/wayfinder/verification/strategies/hash-verifier.d.ts

@@ -1,26 +0,0 @@
-/**
- * Copyright (C) 2022-2024 Permanent Data Solutions, Inc.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-import { DataHashProvider, DataStream, DataVerificationStrategy } from '../../../../types/wayfinder.js';
-export declare class HashVerificationStrategy implements DataVerificationStrategy {
-    private readonly trustedHashProvider;
-    constructor({ trustedHashProvider, }: {
-        trustedHashProvider: DataHashProvider;
-    });
-    verifyData({ data, txId, }: {
-        data: DataStream;
-        txId: string;
-    }): Promise<void>;
-}

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

@@ -1,51 +0,0 @@
-/**
- * Copyright (C) 2022-2024 Permanent Data Solutions, Inc.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-import { DataHashProvider, DataRootProvider } from '../../../types/wayfinder.js';
-import { GatewaysProvider } from '../../../types/wayfinder.js';
-export declare class TrustedGatewaysHashProvider implements DataHashProvider, DataRootProvider {
-    private gatewaysProvider;
-    constructor({ gatewaysProvider, }: {
-        gatewaysProvider: GatewaysProvider;
-    });
-    /**
-     * Gets the digest for a given txId from all trusted gateways and ensures they all match.
-     * @param txId - The txId to get the digest for.
-     * @returns The digest for the given txId.
-     */
-    getHash({ txId, }: {
-        txId: string;
-    }): Promise<{
-        hash: string;
-        algorithm: 'sha256';
-    }>;
-    /**
-     * Get the data root for a given txId from all trusted gateways and ensure they all match.
-     * @param txId - The txId to get the data root for.
-     * @returns The data root for the given txId.
-     */
-    getDataRoot({ txId }: {
-        txId: string;
-    }): Promise<string>;
-}
-/**
- * Note from @djwhitt
- *
- * Calculating data roots this way is fine, but it may not reproduce the original data root.
- * We could also implement a data root verifier that pulls all the chunks, checks that they
- * reproduce the expected data root, and then compares the concatenated chunk data to the
- * original data retrieved. That would take a while, but it should be able to verify any L1
- * data where we can find the chunks.
- */

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

@@ -1,257 +0,0 @@
-/**
- * Copyright (C) 2022-2024 Permanent Data Solutions, Inc.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-import { EventEmitter } from 'eventemitter3';
-import { DataVerificationStrategy, GatewaysProvider, RoutingStrategy } from '../../types/wayfinder.js';
-import { Logger } from '../logger.js';
-type WayfinderHttpClient = typeof fetch;
-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 | URL;
-    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 | URL;
-        selectedGateway: URL;
-        logger?: Logger;
-    }) => URL;
-    verifyData?: DataVerificationStrategy["verifyData"];
-    logger?: Logger;
-    emitter?: WayfinderEmitter;
-    strict?: boolean;
-}) => (url: string, init?: RequestInit) => Promise<Response>;
-/**
- * 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 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 wayfind('ar://example');
-     */
-    readonly emitter: WayfinderEmitter;
-    /**
-     * The constructor for the wayfinder
-     * @param routingStrategy - the routing strategy to use for requests
-     * @param verificationStrategy - the verification strategy to use for requests
-     * @param gatewaysProvider - the gateways provider to use for routing requests
-     * @param logger - the logger to use for logging
-     * @param strict - if true, verification will be blocking and will fail requests if verification fails; if false, verification will be non-blocking
-     */
-    constructor({ logger, gatewaysProvider, routingStrategy, verificationStrategy, events, strict, }?: {
-        routingStrategy?: RoutingStrategy;
-        gatewaysProvider?: GatewaysProvider;
-        verificationStrategy?: DataVerificationStrategy;
-        logger?: Logger;
-        events?: WayfinderEventArgs;
-        strict?: boolean;
-    });
-}
-export {};

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

@@ -1,66 +0,0 @@
-/**
- * Copyright (C) 2022-2024 Permanent Data Solutions, Inc.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-export interface RoutingStrategy {
-    selectGateway: ({ gateways }: {
-        gateways: URL[];
-    }) => Promise<URL>;
-}
-export interface GatewaysProvider {
-    getGateways: () => Promise<URL[]>;
-}
-export type DataStream = AsyncIterable<Uint8Array> | ReadableStream<Uint8Array>;
-export interface DataVerificationStrategy {
-    /**
-     * 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: DataStream;
-        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>;
-}