@midnight-ntwrk/wallet-sdk-utilities 1.0.0-beta.10

package/dist/ArrayOps.d.ts

@@ -0,0 +1,16 @@
+import { NonEmptyReadonlyArray } from 'effect/Array';
+export declare const fold: {
+    <T>(folder: (acc: T, item: T) => T): (arr: NonEmptyReadonlyArray<T>) => T;
+    <T>(arr: NonEmptyReadonlyArray<T>, folder: (acc: T, item: T) => T): T;
+};
+export type Monoid<T> = {
+    empty: T;
+    combine: (a: T, b: T) => T;
+};
+export declare const generalSum: {
+    <T>(monoid: Monoid<T>): (arr: ReadonlyArray<T>) => T;
+    <T>(arr: ReadonlyArray<T>, monoid: Monoid<T>): T;
+};
+export declare const sumNumber: (arr: ReadonlyArray<number>) => number;
+export declare const sumBigInt: (arr: ReadonlyArray<bigint>) => bigint;
+export declare const assertNonEmpty: <T>(arr: ReadonlyArray<T>) => NonEmptyReadonlyArray<T>;

package/dist/ArrayOps.js

@@ -0,0 +1,34 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) 2025 Midnight Foundation
+// SPDX-License-Identifier: Apache-2.0
+// 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 { reduce, match } from 'effect/Array';
+import { dual } from 'effect/Function';
+export const fold = dual(2, (arr, folder) => arr.reduce(folder));
+export const generalSum = dual(2, (arr, monoid) => reduce(arr, monoid.empty, monoid.combine));
+const numberAdditionMonoid = {
+    empty: 0,
+    combine: (a, b) => a + b,
+};
+const bigintAdditionMonoid = {
+    empty: 0n,
+    combine: (a, b) => a + b,
+};
+export const sumNumber = generalSum(numberAdditionMonoid);
+export const sumBigInt = generalSum(bigintAdditionMonoid);
+export const assertNonEmpty = (arr) => {
+    return match(arr, {
+        onNonEmpty: (refined) => refined,
+        onEmpty: () => {
+            throw new Error('Expected non-empty array');
+        },
+    });
+};

package/dist/BlobOps.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Browser-compatible utility for converting a Blob to Uint8Array.
+ * Uses arrayBuffer() instead of bytes() for broader browser support.
+ *
+ * @param blob The Blob to convert to bytes
+ * @returns A Promise that resolves to a Uint8Array containing the blob's bytes
+ */
+export declare const getBytes: (blob: Blob) => Promise<Uint8Array>;

package/dist/BlobOps.js

@@ -0,0 +1,20 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) 2025 Midnight Foundation
+// SPDX-License-Identifier: Apache-2.0
+// 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.
+/**
+ * Browser-compatible utility for converting a Blob to Uint8Array.
+ * Uses arrayBuffer() instead of bytes() for broader browser support.
+ *
+ * @param blob The Blob to convert to bytes
+ * @returns A Promise that resolves to a Uint8Array containing the blob's bytes
+ */
+export const getBytes = (blob) => blob.arrayBuffer().then((ab) => new Uint8Array(ab));

package/dist/DateOps.d.ts

@@ -0,0 +1,3 @@
+export declare const dateToSeconds: (date: Date) => bigint;
+export declare const secondsToDate: (seconds: bigint | number) => Date;
+export declare const addSeconds: (time: Date, seconds: bigint | number) => Date;

package/dist/DateOps.js

@@ -0,0 +1,21 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) 2025 Midnight Foundation
+// SPDX-License-Identifier: Apache-2.0
+// 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 const dateToSeconds = (date) => {
+    return BigInt(Math.floor(date.getTime() / 1000));
+};
+export const secondsToDate = (seconds) => {
+    return new Date(Number(seconds) * 1000);
+};
+export const addSeconds = (time, seconds) => {
+    return new Date(+time + Number(seconds) * 1000);
+};

package/dist/EitherOps.d.ts

@@ -0,0 +1,19 @@
+import { Effect, Either } from 'effect';
+export declare const toEffect: <L, R>(either: Either.Either<R, L>) => Effect.Effect<R, L>;
+export declare const flatMapLeft: {
+    <R, L, L2>(either: Either.Either<R, L>, cb: (l: L) => Either.Either<R, L2>): Either.Either<R, L2>;
+    <R, L, L2>(cb: (l: L) => Either.Either<R, L2>): (either: Either.Either<R, L>) => Either.Either<R, L2>;
+};
+declare const LeftError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "LeftError";
+} & Readonly<A>;
+export declare class LeftError<L> extends LeftError_base<{
+    message: string;
+    cause: L;
+}> {
+    constructor({ cause }: {
+        cause: L;
+    });
+}
+export declare const getOrThrowLeft: <L, R>(either: Either.Either<R, L>) => R;
+export {};

package/dist/EitherOps.js

@@ -0,0 +1,39 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) 2025 Midnight Foundation
+// SPDX-License-Identifier: Apache-2.0
+// 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 { Effect, Either, Data } from 'effect';
+import { dual } from 'effect/Function';
+export const toEffect = (either) => {
+    return Either.match(either, {
+        onLeft: (l) => Effect.fail(l),
+        onRight: (r) => Effect.succeed(r),
+    });
+};
+export const flatMapLeft = dual(2, (either, cb) => {
+    return Either.match(either, {
+        onRight: (r) => Either.right(r),
+        onLeft: cb,
+    });
+});
+export class LeftError extends Data.TaggedError('LeftError') {
+    constructor({ cause }) {
+        super({ message: 'Unexpected left value', cause });
+    }
+}
+export const getOrThrowLeft = (either) => {
+    return Either.match(either, {
+        onRight: (r) => r,
+        onLeft: (l) => {
+            throw new LeftError({ cause: l });
+        },
+    });
+};

package/dist/Fluent.d.ts

@@ -0,0 +1,6 @@
+export declare namespace Fluent {
+    /**
+     * Exclude named methods from `T` so that they are no longer callable.
+     */
+    type ExcludeMethod<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>>;
+}

package/dist/Fluent.js

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

package/dist/LedgerOps.d.ts

@@ -0,0 +1,13 @@
+import { Either } from 'effect';
+declare const LedgerError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "LedgerError";
+} & Readonly<A>;
+export declare class LedgerError extends LedgerError_base<{
+    readonly message: string;
+    readonly cause?: unknown;
+}> {
+}
+export declare const ledgerTry: <A>(fn: () => A) => Either.Either<A, LedgerError>;
+export declare const generateHex: (len: number) => string;
+export declare const randomNonce: () => string;
+export {};

package/dist/LedgerOps.js

@@ -0,0 +1,28 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) 2025 Midnight Foundation
+// SPDX-License-Identifier: Apache-2.0
+// 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 { Either, Data } from 'effect';
+export class LedgerError extends Data.TaggedError('LedgerError') {
+}
+export const ledgerTry = (fn) => {
+    return Either.try({
+        try: fn,
+        catch: (error) => {
+            const message = error instanceof Error ? error.message : `${error?.toString()}`;
+            return new LedgerError({ message: `Error from ledger: ${message}`, cause: error });
+        },
+    });
+};
+export const generateHex = (len) => {
+    return Buffer.from(crypto.getRandomValues(new Uint8Array(len / 2))).toString('hex');
+};
+export const randomNonce = () => generateHex(64);

package/dist/ObservableOps.d.ts

@@ -0,0 +1,16 @@
+import { Stream } from 'effect';
+import { Observable } from 'rxjs';
+/**
+ * A utility that creates a Rx.js `Observable` from a given Effect `Stream`.
+ *
+ * @param stream The Effect `Stream` from which an `Observable` is required.
+ * @returns A Rx.js `Observable` that consumes the elements from `stream`.
+ */
+export declare const fromStream: <A, E = never>(stream: Stream.Stream<A, E>) => Observable<A>;
+/**
+ * A utility that creates an Effect `Stream` from a given Rx.js `Observable`.
+ *
+ * @param observable The Rx.js `Observable` from which a `Stream` is required.
+ * @returns A `Stream` the consumes elements from `observable`.
+ */
+export declare const toStream: <A, E = never>(observable: Observable<A>) => Stream.Stream<A, E>;

package/dist/ObservableOps.js

@@ -0,0 +1,65 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) 2025 Midnight Foundation
+// SPDX-License-Identifier: Apache-2.0
+// 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 { Effect, Stream, Fiber, Option, Chunk } from 'effect';
+import { Observable } from 'rxjs';
+/**
+ * A utility that creates a Rx.js `Observable` from a given Effect `Stream`.
+ *
+ * @param stream The Effect `Stream` from which an `Observable` is required.
+ * @returns A Rx.js `Observable` that consumes the elements from `stream`.
+ */
+export const fromStream = (stream) => new Observable((subscriber) => {
+    const fiber = Effect.runFork(Effect.scoped(Effect.gen(function* () {
+        const pull = yield* Stream.toPull(stream);
+        while (true) {
+            const shouldBreak = yield* Effect.match(pull, {
+                onSuccess(values) {
+                    Chunk.forEach(values, (element) => {
+                        subscriber.next(element);
+                    });
+                    return false;
+                },
+                onFailure(error) {
+                    return Option.match(error, {
+                        onNone() {
+                            subscriber.complete();
+                            return true; // Stream has completed, signal the break.
+                        },
+                        onSome: (err) => {
+                            subscriber.error(err);
+                            return true;
+                        },
+                    });
+                },
+            });
+            if (shouldBreak)
+                break;
+        }
+    })));
+    // Ensure that if the subscription ends we also dispose of the fiber pulling from the stream.
+    subscriber.add(() => Effect.runFork(Fiber.interrupt(fiber)));
+});
+/**
+ * A utility that creates an Effect `Stream` from a given Rx.js `Observable`.
+ *
+ * @param observable The Rx.js `Observable` from which a `Stream` is required.
+ * @returns A `Stream` the consumes elements from `observable`.
+ */
+export const toStream = (observable) => Stream.async((emit) => {
+    const subscription = observable.subscribe({
+        next: (value) => void emit.single(value),
+        error: (err) => void emit.fail(err),
+        complete: () => void emit.end(),
+    });
+    return Effect.sync(() => subscription.unsubscribe());
+});

package/dist/RecordOps.d.ts

@@ -0,0 +1,2 @@
+export declare const merge: <K extends string | number | symbol, T>(combine: (a: T, b: T) => T) => (records: Array<Record<K, T>>) => Record<K, T>;
+export declare const mergeWithAccumulator: <K extends string | number | symbol, T, S>(mempty: S, combine: (acc: S, b: T) => S) => (records: Array<Record<K, T>>) => Record<K, S>;

package/dist/RecordOps.js

@@ -0,0 +1,40 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) 2025 Midnight Foundation
+// SPDX-License-Identifier: Apache-2.0
+// 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 const merge = (combine) => (records) => {
+    const result = {};
+    for (const record of records) {
+        for (const key in record) {
+            if (Object.hasOwn(result, key)) {
+                result[key] = combine(result[key], record[key]);
+            }
+            else {
+                result[key] = record[key];
+            }
+        }
+    }
+    return result;
+};
+export const mergeWithAccumulator = (mempty, combine) => (records) => {
+    const result = {};
+    for (const record of records) {
+        for (const key in record) {
+            if (Object.hasOwn(result, key)) {
+                result[key] = combine(result[key], record[key]);
+            }
+            else {
+                result[key] = combine(mempty, record[key]);
+            }
+        }
+    }
+    return result;
+};

package/dist/hlist.d.ts

@@ -0,0 +1,26 @@
+import { PolyFunction, WithTag } from './polyFunction.js';
+/**
+ * Heterogeneous list - as in - list, where elements have different types
+ * Here - more as an additional API over TS's tuple type
+ */
+export type Empty = [];
+export type NonEmpty<T> = T extends Array<infer E> ? [E, ...T] : never;
+export type Prepend<List extends unknown[], Element> = [Element, ...List];
+export type Append<List extends unknown[], Element> = [...List, Element];
+export type Reverse<List extends unknown[]> = List extends [...infer Init, infer Last] ? [Last, ...Reverse<Init>] : List extends [] ? [] : never;
+export type HeadOr<List, Default> = List extends [infer TheHead, ...any[]] ? TheHead : List extends [] ? Default : never;
+export type Head<List extends any[]> = HeadOr<List, never>;
+export type Tail<List extends unknown[]> = List extends [unknown, ...infer Tail] ? Tail : [];
+export type Tails<List extends unknown[]> = List extends [unknown, ...infer Tail] ? Tails<Tail> | Tail : [];
+export type Each<List extends unknown[]> = List[number];
+export type Find<List extends any[], Predicate> = List extends [infer TheHead, ...infer Rest] ? TheHead extends Predicate ? TheHead : Find<Rest, Predicate> : never;
+export declare const empty: Empty;
+export declare const prepend: <List extends unknown[], Element>(list: List, element: Element) => Prepend<List, Element>;
+export declare const append: <List extends unknown[], Element>(list: List, element: Element) => Append<List, Element>;
+export declare function headOr<List extends unknown[], Default>(list: List, def: () => Default): HeadOr<List, Default>;
+export declare const head: <List extends unknown[]>(list: List) => Head<List>;
+export declare const tail: <List extends unknown[]>(list: List) => Tail<List>;
+export declare const reverse: <List extends unknown[]>(list: List) => Reverse<List>;
+export declare const find: <List extends unknown[], Predicate>(list: List, predicate: (value: Each<List>) => value is Predicate) => Find<List, Predicate>;
+export declare const foldLeft: <List extends WithTag<string | symbol>[], Acc>(list: List, acc: Acc, folder: (acc: Acc) => PolyFunction<Each<List>, Acc>) => Acc;
+export declare const foldRight: <List extends WithTag<string | symbol>[], Acc>(list: List, acc: Acc, folder: (acc: Acc) => PolyFunction<Each<List>, Acc>) => Acc;

package/dist/hlist.js

@@ -0,0 +1,49 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) 2025 Midnight Foundation
+// SPDX-License-Identifier: Apache-2.0
+// 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.
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { dispatch } from './polyFunction.js';
+export const empty = [];
+export const prepend = (list, element) => {
+    return [element, ...list];
+};
+export const append = (list, element) => {
+    return [...list, element];
+};
+export function headOr(list, def) {
+    if (list.length == 0) {
+        return def();
+    }
+    else {
+        return list.at(0);
+    }
+}
+export const head = (list) => {
+    return headOr(list, () => {
+        throw new Error('Cannot get head from empty hlist');
+    });
+};
+export const tail = (list) => {
+    return list.toSpliced(0, 1);
+};
+export const reverse = (list) => {
+    return list.toReversed();
+};
+export const find = (list, predicate) => {
+    return list.find(predicate);
+};
+export const foldLeft = (list, acc, folder) => {
+    return list.reduce((acc, item) => dispatch(item, folder(acc)), acc);
+};
+export const foldRight = (list, acc, folder) => {
+    return list.reduceRight((acc, item) => dispatch(item, folder(acc)), acc);
+};

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * as ArrayOps from './ArrayOps.js';
+export * as BlobOps from './BlobOps.js';
+export * as DateOps from './DateOps.js';
+export * as EitherOps from './EitherOps.js';
+export * as Fluent from './Fluent.js';
+export * as HList from './hlist.js';
+export * as LedgerOps from './LedgerOps.js';
+export * as ObservableOps from './ObservableOps.js';
+export * as Poly from './polyFunction.js';
+export * as RecordOps from './RecordOps.js';

package/dist/index.js

@@ -0,0 +1,22 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) 2025 Midnight Foundation
+// SPDX-License-Identifier: Apache-2.0
+// 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 * as ArrayOps from './ArrayOps.js';
+export * as BlobOps from './BlobOps.js';
+export * as DateOps from './DateOps.js';
+export * as EitherOps from './EitherOps.js';
+export * as Fluent from './Fluent.js';
+export * as HList from './hlist.js';
+export * as LedgerOps from './LedgerOps.js';
+export * as ObservableOps from './ObservableOps.js';
+export * as Poly from './polyFunction.js';
+export * as RecordOps from './RecordOps.js';

package/dist/networking/ClientServerErrors.d.ts

@@ -0,0 +1,26 @@
+declare const ClientError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "ClientError";
+} & Readonly<A>;
+/**
+ * An error representing a connection or client-side error.
+ *
+ * @remarks
+ * This error typically indicates a connection issue with a target server, or when the client has submitted some
+ * data that could not be processed.
+ */
+export declare class ClientError extends ClientError_base<{
+    readonly message: string;
+    readonly cause?: unknown;
+}> {
+}
+declare const ServerError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "ServerError";
+} & Readonly<A>;
+/**
+ * An error representing a server-side error.
+ */
+export declare class ServerError extends ServerError_base<{
+    readonly message: string;
+}> {
+}
+export {};

package/dist/networking/ClientServerErrors.js

@@ -0,0 +1,27 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) 2025 Midnight Foundation
+// SPDX-License-Identifier: Apache-2.0
+// 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 { Data } from 'effect';
+/**
+ * An error representing a connection or client-side error.
+ *
+ * @remarks
+ * This error typically indicates a connection issue with a target server, or when the client has submitted some
+ * data that could not be processed.
+ */
+export class ClientError extends Data.TaggedError('ClientError') {
+}
+/**
+ * An error representing a server-side error.
+ */
+export class ServerError extends Data.TaggedError('ServerError') {
+}

package/dist/networking/HttpURL.d.ts

@@ -0,0 +1,19 @@
+import { Either } from 'effect';
+import * as Brand from 'effect/Brand';
+import { InvalidProtocolSchemeError } from './URLError.js';
+/**
+ * A 'HTTP' URL.
+ */
+export type HttpUrl = Brand.Branded<URL, 'HttpURL'>;
+/**
+ * Constructs a 'HTTP' URL from a source URL, ensuring that the protocol is correct.
+ */
+export declare const HttpURL: Brand.Brand.Constructor<HttpUrl>;
+/**
+ * Constructs a new {@link HttpURL} from a given string.
+ *
+ * @param url The URL to be made into a HTTP URL.
+ * @returns An `Either` that represents the valid HTTP URL constructed from `url`; or an
+ * {@link InvalidProtocolSchemeError}.
+ */
+export declare const make: (url: URL | string) => Either.Either<HttpUrl, InvalidProtocolSchemeError>;

package/dist/networking/HttpURL.js

@@ -0,0 +1,35 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) 2025 Midnight Foundation
+// SPDX-License-Identifier: Apache-2.0
+// 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 { Either } from 'effect';
+import * as Brand from 'effect/Brand';
+import { InvalidProtocolSchemeError } from './URLError.js';
+/**
+ * Constructs a 'HTTP' URL from a source URL, ensuring that the protocol is correct.
+ */
+export const HttpURL = Brand.refined((url) => url.protocol === 'http:' || url.protocol === 'https:', (url) => Brand.error(`Invalid protocol scheme '${url.protocol}'. Expected 'http:' or 'https:'`));
+/**
+ * Constructs a new {@link HttpURL} from a given string.
+ *
+ * @param url The URL to be made into a HTTP URL.
+ * @returns An `Either` that represents the valid HTTP URL constructed from `url`; or an
+ * {@link InvalidProtocolSchemeError}.
+ */
+export const make = (url) => {
+    const targetURL = new URL(url);
+    try {
+        return Either.right(HttpURL(targetURL));
+    }
+    catch (err) {
+        return Either.left(new InvalidProtocolSchemeError({ message: String(err), invalidScheme: targetURL.protocol }));
+    }
+};

package/dist/networking/URLError.d.ts

@@ -0,0 +1,27 @@
+declare const InvalidProtocolSchemeError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "InvalidProtocolSchemeError";
+} & Readonly<A>;
+/**
+ * A configuration error where the protocol scheme of a given server URL was unexpected (e.g., used
+ * `'ftp:'` rather than `'http:'` for a server running over HTTP).
+ */
+export declare class InvalidProtocolSchemeError extends InvalidProtocolSchemeError_base<{
+    /** A message describing the error. */
+    readonly message: string;
+    /** The scheme that caused the error. */
+    readonly invalidScheme: string;
+}> {
+    static readonly tag: "InvalidProtocolSchemeError";
+}
+declare const FailedToDeriveWebSocketUrlError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "FailedToDeriveWebSocketUrlError";
+} & Readonly<A>;
+export declare class FailedToDeriveWebSocketUrlError extends FailedToDeriveWebSocketUrlError_base<{
+    /** A message describing the error. */
+    readonly message: string;
+    readonly cause?: unknown;
+}> {
+    static readonly tag: "FailedToDeriveWebSocketUrlError";
+}
+export type URLError = InvalidProtocolSchemeError | FailedToDeriveWebSocketUrlError;
+export {};

package/dist/networking/URLError.js

@@ -0,0 +1,23 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) 2025 Midnight Foundation
+// SPDX-License-Identifier: Apache-2.0
+// 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 { Data } from 'effect';
+/**
+ * A configuration error where the protocol scheme of a given server URL was unexpected (e.g., used
+ * `'ftp:'` rather than `'http:'` for a server running over HTTP).
+ */
+export class InvalidProtocolSchemeError extends Data.TaggedError('InvalidProtocolSchemeError') {
+    static tag = 'InvalidProtocolSchemeError';
+}
+export class FailedToDeriveWebSocketUrlError extends Data.TaggedError('FailedToDeriveWebSocketUrlError') {
+    static tag = 'FailedToDeriveWebSocketUrlError';
+}

package/dist/networking/WsURL.d.ts

@@ -0,0 +1,19 @@
+import { Either } from 'effect';
+import * as Brand from 'effect/Brand';
+import { InvalidProtocolSchemeError } from './URLError.js';
+/**
+ * A 'HTTP' URL.
+ */
+export type WsURL = Brand.Branded<URL, 'WsURL'>;
+/**
+ * Constructs a 'WS' URL from a source URL, ensuring that the protocol is correct.
+ */
+export declare const WsURL: Brand.Brand.Constructor<WsURL>;
+/**
+ * Constructs a new {@link WsURL} from a given string.
+ *
+ * @param url The URL to be made into a WebSocket URL.
+ * @returns An `Either` that represents the valid WebSocket URL constructed from `url`; or an
+ * {@link InvalidProtocolSchemeError}.
+ */
+export declare const make: (url: URL | string) => Either.Either<WsURL, InvalidProtocolSchemeError>;

package/dist/networking/WsURL.js

@@ -0,0 +1,35 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) 2025 Midnight Foundation
+// SPDX-License-Identifier: Apache-2.0
+// 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 { Either } from 'effect';
+import * as Brand from 'effect/Brand';
+import { InvalidProtocolSchemeError } from './URLError.js';
+/**
+ * Constructs a 'WS' URL from a source URL, ensuring that the protocol is correct.
+ */
+export const WsURL = Brand.refined((url) => url.protocol === 'ws:' || url.protocol === 'wss:', (url) => Brand.error(`Invalid protocol scheme '${url.protocol}'. Expected 'ws:' or 'wss:'`));
+/**
+ * Constructs a new {@link WsURL} from a given string.
+ *
+ * @param url The URL to be made into a WebSocket URL.
+ * @returns An `Either` that represents the valid WebSocket URL constructed from `url`; or an
+ * {@link InvalidProtocolSchemeError}.
+ */
+export const make = (url) => {
+    const targetURL = new URL(url);
+    try {
+        return Either.right(WsURL(targetURL));
+    }
+    catch (err) {
+        return Either.left(new InvalidProtocolSchemeError({ message: String(err), invalidScheme: targetURL.protocol }));
+    }
+};

package/dist/networking/index.d.ts

@@ -0,0 +1,4 @@
+export * as HttpURL from './HttpURL.js';
+export * as WsURL from './WsURL.js';
+export * from './URLError.js';
+export * from './ClientServerErrors.js';

package/dist/networking/index.js

@@ -0,0 +1,16 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) 2025 Midnight Foundation
+// SPDX-License-Identifier: Apache-2.0
+// 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 * as HttpURL from './HttpURL.js';
+export * as WsURL from './WsURL.js';
+export * from './URLError.js';
+export * from './ClientServerErrors.js';

package/dist/polyFunction.d.ts

@@ -0,0 +1,14 @@
+export type WithTag<T extends string | symbol> = {
+    __polyTag__: T;
+};
+export type TagOf<T> = T extends WithTag<infer Tag> ? Tag : never;
+export type WithTagFrom<T> = WithTag<TagOf<T>>;
+/**
+ * Polymorphic function - function defined for multiple types at once
+ * Leveraging tagging mechanics it can predictably work at runtime and be quite intuitively defined by hand
+ */
+export type PolyFunction<Variants extends WithTag<string | symbol>, T> = {
+    [V in Variants as TagOf<V>]: (variant: V) => T;
+};
+export declare const getTag: <TTag extends string | symbol>(t: WithTag<TTag>) => TTag;
+export declare const dispatch: <TVariant extends WithTag<string | symbol>, TResult>(subject: TVariant, impl: PolyFunction<TVariant, TResult>) => TResult;

package/dist/polyFunction.js

@@ -0,0 +1,12 @@
+export const getTag = (t) => t.__polyTag__;
+export const dispatch = (subject, impl) => {
+    if (subject.__polyTag__ in impl) {
+        //Sadly, the type casts below are needed because eslint or TS limitations
+        const subjectTag = subject.__polyTag__;
+        const chosen = impl[subjectTag];
+        return chosen(subject);
+    }
+    else {
+        throw new Error(`Not found implementation for ${String(subject.__polyTag__)}`);
+    }
+};

package/dist/testUtils.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A utility type that ensures that a given type is `true` or otherwise forces a compile time error.
+ */
+export type Expect<T extends true> = T;
+/**
+ * A utility type that exactly compares two types for equality.
+ */
+export type Equal<X, Y> = (<T>() => T extends X ? 1 : 2) extends <T>() => T extends Y ? 1 : 2 ? true : false;
+export type ItemType<T> = T extends ReadonlyArray<infer R> ? R : never;

package/dist/testUtils.js

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

package/dist/testing/compose.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Gets the absolute path to the repository root directory.
+ *
+ * @returns The absolute path to the repository root
+ */
+export declare function getRepositoryRoot(): string;
+/**
+ * Gets the absolute path to the docker compose directory.
+ *
+ * @returns The absolute path to the compose directory
+ */
+export declare function getComposeDirectory(): string;
+/**
+ * Options for building test environment variables.
+ */
+export interface BuildTestEnvironmentVariablesOptions {
+    /**
+     * Additional environment variables to include.
+     * These will be merged with the variables collected from process.env.
+     */
+    additionalVars?: Record<string, string>;
+}
+/**
+ * Builds and validates environment variables for test containers.
+ * Throws an error if any required environment variable from envVarsToPass is missing.
+ *
+ * @param envVarsToPass - Array of environment variable names to collect from process.env
+ * @param options - Optional configuration for building environment variables
+ * @returns Record of environment variables to pass to Docker Compose
+ */
+export declare function buildTestEnvironmentVariables(envVarsToPass: readonly string[], options?: BuildTestEnvironmentVariablesOptions): Record<string, string>;

package/dist/testing/compose.js

@@ -0,0 +1,58 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) 2025 Midnight Foundation
+// SPDX-License-Identifier: Apache-2.0
+// 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 * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * Gets the absolute path to the repository root directory.
+ *
+ * @returns The absolute path to the repository root
+ */
+export function getRepositoryRoot() {
+    const currentFile = fileURLToPath(import.meta.url);
+    const currentDir = path.dirname(currentFile);
+    return path.resolve(currentDir, '../../../../');
+}
+/**
+ * Gets the absolute path to the docker compose directory.
+ *
+ * @returns The absolute path to the compose directory
+ */
+export function getComposeDirectory() {
+    const repoRoot = getRepositoryRoot();
+    return path.join(repoRoot, 'infra', 'compose');
+}
+/**
+ * Builds and validates environment variables for test containers.
+ * Throws an error if any required environment variable from envVarsToPass is missing.
+ *
+ * @param envVarsToPass - Array of environment variable names to collect from process.env
+ * @param options - Optional configuration for building environment variables
+ * @returns Record of environment variables to pass to Docker Compose
+ */
+export function buildTestEnvironmentVariables(envVarsToPass, options) {
+    // Add any additional vars first (so they can be overridden by process.env vars if needed)
+    const environmentVars = {
+        ...options?.additionalVars,
+    };
+    // Collect and validate required environment variables
+    for (const envVar of envVarsToPass) {
+        const value = process.env[envVar];
+        if (value) {
+            environmentVars[envVar] = value;
+        }
+        else {
+            throw new Error(`Required environment variable ${envVar} is not set. Please ensure it is exported in your shell or CI environment.`);
+        }
+    }
+    return environmentVars;
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,2 @@
+export * as TestContainers from './test-containers.js';
+export * from './compose.js';

package/dist/testing/index.js

@@ -0,0 +1,14 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) 2025 Midnight Foundation
+// SPDX-License-Identifier: Apache-2.0
+// 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 * as TestContainers from './test-containers.js';
+export * from './compose.js';

package/dist/testing/test-containers.d.ts

@@ -0,0 +1,13 @@
+import { Effect, Scope } from 'effect';
+import { GenericContainer, StartedNetwork, type StartedTestContainer } from 'testcontainers';
+export declare const createNetwork: () => Effect.Effect<StartedNetwork, never, Scope.Scope>;
+export declare const runNodeContainer: (adjustment?: (t: GenericContainer) => GenericContainer) => Effect.Effect<StartedTestContainer, Error, Scope.Scope>;
+export declare const runProofServerContainer: (adjustment?: (t: GenericContainer) => GenericContainer) => Effect.Effect<StartedTestContainer, Error, Scope.Scope>;
+export declare const runTxGenerator: (config: {
+    nodeUrl: string;
+    destPath: string;
+    fileName: string;
+    txsPerBatch: number;
+    batches: number;
+}, adjustment?: (t: GenericContainer) => GenericContainer) => Effect.Effect<StartedTestContainer, Error, Scope.Scope>;
+export declare const findAvailablePort: Effect.Effect<number>;

package/dist/testing/test-containers.js

@@ -0,0 +1,58 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) 2025 Midnight Foundation
+// SPDX-License-Identifier: Apache-2.0
+// 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 { Effect, identity } from 'effect';
+import { GenericContainer, Network, Wait } from 'testcontainers';
+import { getPortPromise } from 'portfinder';
+export const createNetwork = () => Effect.acquireRelease(Effect.promise(() => new Network().start()), (net) => Effect.promise(() => net.stop()));
+const startContainer = (container) => {
+    return Effect.acquireRelease(Effect.promise(() => container.start()), (container) => Effect.promise(() => container.stop({ timeout: 5_000 })));
+};
+export const runNodeContainer = (adjustment = identity) => {
+    const container = new GenericContainer('ghcr.io/midnight-ntwrk/midnight-node:0.20.0-alpha.1')
+        .withEnvironment({
+        CFG_PRESET: 'dev',
+        SIDECHAIN_BLOCK_BENEFICIARY: '04bcf7ad3be7a5c790460be82a713af570f22e0f801f6659ab8e84a52be6969e',
+    })
+        .withExposedPorts(9944)
+        .withWaitStrategy(Wait.forListeningPorts());
+    return startContainer(adjustment(container));
+};
+export const runProofServerContainer = (adjustment = identity) => {
+    const container = new GenericContainer('ghcr.io/midnight-ntwrk/proof-server:7.0.0-rc.1')
+        .withEnvironment({
+        RUST_BACKTRACE: 'full',
+    })
+        .withExposedPorts(6300)
+        .withCommand(['midnight-proof-server -v'])
+        .withWaitStrategy(Wait.forListeningPorts());
+    return startContainer(adjustment(container));
+};
+export const runTxGenerator = (config, adjustment = identity) => {
+    const container = new GenericContainer('ghcr.io/midnight-ntwrk/midnight-node-toolkit:0.20.0-alpha.1')
+        .withBindMounts([{ source: config.destPath, target: '/tmp', mode: 'rw' }])
+        .withCommand([
+        'generate-txs',
+        '--src-url',
+        config.nodeUrl,
+        '--dest-file',
+        `/tmp/${config.fileName}`,
+        'batches',
+        '--num-batches',
+        String(config.batches),
+        '--num-txs-per-batch',
+        String(config.txsPerBatch),
+    ])
+        .withWaitStrategy(Wait.forLogMessage('✓ generated transactions'));
+    return startContainer(adjustment(container));
+};
+export const findAvailablePort = Effect.promise(() => getPortPromise());

package/dist/types.d.ts

@@ -0,0 +1,15 @@
+/**
+ * A utility type that checks whether type A can be assigned to type To
+ * It appears to be useful when exact inferred type are slightly too complex to express and we want the express
+ * a slightly simplified type rule like Expect<CanAssign<{foo: number}, object & {foo: number}>>
+ */
+export type CanAssign<A, To> = A extends To ? true : false;
+/**
+ * A utility type that ensures that a given type is `true` or otherwise forces a compile time error.
+ */
+export type Expect<T extends true> = T;
+export type ItemType<T> = T extends ReadonlyArray<infer R> ? R : never;
+/**
+ * A utility type that exactly compares two types for equality.
+ */
+export type Equal<X, Y> = (<T>() => T extends X ? 1 : 2) extends <T>() => T extends Y ? 1 : 2 ? true : false;

package/dist/types.js

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

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@midnight-ntwrk/wallet-sdk-utilities",
+  "description": "Domain-agnostic utilities for the wallet SDK - common operations and types",
+  "version": "1.0.0-beta.10",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "author": "Midnight Foundation",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com/"
+  },
+  "files": [
+    "dist/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/midnight-ntwrk/artifacts.git"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./networking": {
+      "types": "./dist/networking/index.d.ts",
+      "import": "./dist/networking/index.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js"
+    }
+  },
+  "dependencies": {
+    "effect": "^3.17.3",
+    "portfinder": "^1.0.37",
+    "rxjs": "^7.5",
+    "testcontainers": "^11.10.0"
+  },
+  "scripts": {
+    "typecheck": "tsc -b ./tsconfig.json --noEmit",
+    "test": "vitest run",
+    "lint": "eslint --max-warnings 0",
+    "format": "prettier --write \"**/*.{ts,js,json,yaml,yml,md}\"",
+    "format:check": "prettier --check \"**/*.{ts,js,json,yaml,yml,md}\"",
+    "dist": "tsc -b ./tsconfig.build.json",
+    "dist:publish": "tsc -b ./tsconfig.publish.json",
+    "clean": "rimraf --glob dist 'tsconfig.*.tsbuildinfo' && date +%s > .clean-timestamp",
+    "publint": "publint --strict"
+  },
+  "devDependencies": {
+    "eslint": "^9.37.0",
+    "fast-check": "^4.2.0",
+    "prettier": "^3.7.0",
+    "publint": "~0.3.14",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  }
+}