@ar.io/sdk 3.11.0-alpha.12 → 3.11.0-alpha.13

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

@@ -1,27 +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 { WayfinderRouter } from '../../../types/wayfinder.js';
-import { GatewaysProvider } from '../gateways.js';
-export declare class RandomGatewayRouter implements WayfinderRouter {
-    readonly name = "random";
-    private gatewaysProvider;
-    private blocklist;
-    constructor({ gatewaysProvider, blocklist, }: {
-        gatewaysProvider: GatewaysProvider;
-        blocklist?: string[];
-    });
-    getTargetGateway(): Promise<URL>;
-}

package/lib/types/common/wayfinder/routers/random.test.d.ts

@@ -1 +0,0 @@
-export {};

package/lib/types/common/wayfinder/routers/simple-cache.d.ts

@@ -1,28 +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 { WayfinderRouter } from '../../../types/wayfinder.js';
-export declare class SimpleCacheRouter implements WayfinderRouter {
-    readonly name: 'simple-cache';
-    private lastUpdatedTimestamp;
-    private ttlSeconds;
-    private targetGateway;
-    private router;
-    constructor({ router, ttlSeconds, }: {
-        router: WayfinderRouter;
-        ttlSeconds?: number;
-    });
-    getTargetGateway(): Promise<URL>;
-}

package/lib/types/common/wayfinder/routers/simple-cache.test.d.ts

@@ -1 +0,0 @@
-export {};

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

@@ -1,24 +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 { WayfinderRouter } from '../../../types/wayfinder.js';
-export declare class StaticGatewayRouter implements WayfinderRouter {
-    readonly name = "static";
-    private gateway;
-    constructor({ gateway }: {
-        gateway: string;
-    });
-    getTargetGateway(): Promise<URL>;
-}

package/lib/types/common/wayfinder/routers/static.test.d.ts

@@ -1 +0,0 @@
-export {};

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

@@ -1,31 +0,0 @@
-import { Readable } from 'node:stream';
-import { DataRootProvider, DataVerifier } from '../../../types/wayfinder.js';
-export declare function convertBufferToDataRoot({ buffer, }: {
-    buffer: Buffer;
-}): Promise<string>;
-export declare const convertReadableToDataRoot: <T extends AsyncIterable<Uint8Array>>({ iterable, }: {
-    iterable: T;
-}) => Promise<string>;
-export declare class DataRootVerifier implements DataVerifier {
-    private readonly trustedDataRootProvider;
-    constructor({ trustedDataRootProvider, }: {
-        trustedDataRootProvider: DataRootProvider;
-    });
-    verifyData({ data, txId, }: {
-        data: Buffer | Readable | ReadableStream;
-        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/hash-verifier.d.ts

@@ -1,27 +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 { Readable } from 'node:stream';
-import { DataHashProvider, DataVerifier } from '../../../types/wayfinder.js';
-export declare class HashVerifier implements DataVerifier {
-    private readonly trustedHashProvider;
-    constructor({ trustedHashProvider, }: {
-        trustedHashProvider: DataHashProvider;
-    });
-    verifyData({ data, txId, }: {
-        data: Buffer | Readable | ReadableStream;
-        txId: string;
-    }): Promise<void>;
-}

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

@@ -1,265 +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 'node:events';
-import { PassThrough, Readable } from 'node:stream';
-import { DataHashProvider, DataVerifier, WayfinderRouter } from '../../types/wayfinder.js';
-import { Logger } from '../logger.js';
-type HttpClientArgs = unknown[];
-type HttpClientFunction = (...args: HttpClientArgs) => unknown;
-type WayfinderHttpClient<T extends HttpClientFunction> = T;
-export declare const arnsRegex: RegExp;
-export declare const txIdRegex: RegExp;
-/**
- * Core function to resolve a wayfinder url against a target gateway
- * @param originalUrl - the wayfinder url to resolve
- * @param targetGateway - 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, targetGateway, logger, }: {
-    originalUrl: string | URL;
-    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
- *
- * This function leverages a Proxy to intercept calls to the http client
- * and redirects them to the target gateway using the resolveUrl function url.
- * It also supports the http client methods like get(), post(), put(), delete(), etc.
- *
- * Any URLs provided that are not wayfinder urls will be returned as is.
- *
- * @param httpClient - the http client to wrap (e.g. axios, fetch, got, etc.)
- * @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, 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
- * @param router - the router to use for requests
- * @param httpClient - the http client to use for requests
- * @param blocklist - the blocklist of gateways to avoid
- */
-export declare class Wayfinder<T extends HttpClientFunction> {
-    /**
-     * The router to use for requests
-     *
-     * @example
-     * const wayfinder = new Wayfinder({
-     *   router: new RandomGatewayRouter({
-     *     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 native http client used by wayfinder
-     *
-     * @example
-     * const wayfinder = new Wayfinder({
-     *   router: new RandomGatewayRouter({
-     *     gatewaysProvider: new SimpleCacheGatewaysProvider({
-     *       gatewaysProvider: new NetworkGatewaysProvider({ ario: ARIO.mainnet() }),
-     *       ttlSeconds: 60 * 60 * 24, // 1 day
-     *     }),
-     *   }),
-     *   httpClient: axios,
-     * });
-     *
-     */
-    readonly httpClient: T;
-    /**
-     * The function that resolves the redirect url for ar:// requests to a target gateway
-     *
-     * @example
-     * const wayfinder = new Wayfinder({
-     *   router: new RandomGatewayRouter({
-     *     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: {
-        originalUrl: string;
-        logger?: Logger;
-    }) => Promise<URL>;
-    /**
-     * A wrapped http client that supports ar:// protocol
-     *
-     * @example
-     * const { request: wayfind } = new Wayfinder({
-     *   router: new RandomGatewayRouter({
-     *     gatewaysProvider: new SimpleCacheGatewaysProvider({
-     *       gatewaysProvider: new NetworkGatewaysProvider({ ario: ARIO.mainnet() }),
-     *       ttlSeconds: 60 * 60 * 24, // 1 day
-     *     }),
-     *   }),
-     *   httpClient: axios,
-     * });;
-     *
-     * const response = await wayfind('ar://example', {
-     *   method: 'POST',
-     *   data: {
-     *     name: 'John Doe',
-     *   },
-     * })
-     */
-    readonly request: WayfinderHttpClient<T>;
-    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/common/wayfinder/wayfinder.test.d.ts

@@ -1 +0,0 @@
-export {};

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

@@ -1,62 +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 { 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>;
-}