near-api-ts 0.6.0 → 0.7.1

package/{LICENSE → LICENSE.md}

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright(c) 2025 Volodymyr Bilyk (volodymyr@lantstool.dev)
+Copyright(c) 2025–2026 Volodymyr Bilyk (volodymyr@lantstool.dev)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,14 +1,16 @@
 ## NEAR API TS
+
 TypeScript library for interactions with Near Protocol in the browser or Node.js
 
 [GitHub Repository](https://github.com/eclipseeer/near-api-ts/tree/main)
 
 **Installation**
+
 ```text
 pnpm add near-api-ts
 ```
 
-**Node.js (esm, 22+) / Browser**
+**Node.js (esm, 24+) / Browser**
 
 ```ts
 import {

package/browser/src/idbKeyService/idbKeyService.ts

@@ -0,0 +1,61 @@
+// import * as z from 'zod/mini';
+import { asThrowable } from '@universal/src/_common/utils/asThrowable';
+import { result } from '@universal/src/_common/utils/result';
+import { wrapInternalError } from '@universal/src/_common/utils/wrapInternalError';
+import type { Result } from '@universal/types/_common/common';
+import type { PublicKey } from '@universal/types/_common/crypto';
+import type { KeyPair } from '@universal/types/_common/keyPair/keyPair';
+import { createGetKeyPair } from './private/getKeyPair';
+import { openIdbConnection } from './private/openIdbConnection';
+import { createSafeAddKey } from './public/addKey';
+import { createSafeClear } from './public/clear';
+import { createSafeHasKey } from './public/hasKey';
+import { createSafeRemoveKey } from './public/removeKey';
+import { createSafeSignTransaction } from './public/signTransaction';
+
+export type IdbKeyServiceContext = {
+  idbName: string;
+  idb?: IDBDatabase;
+  keyPairs: Map<PublicKey, KeyPair>;
+  getKeyPair: (publicKey: PublicKey) => Promise<Result<KeyPair, any>>;
+};
+
+export const safeCreateIdbKeyService: any = wrapInternalError(
+  'CreateIdbKeyService.Internal',
+  (args?: any) => {
+    // validate
+
+    const context = {
+      idbName: args?.idbName ?? 'near-api-ts',
+      idb: undefined,
+      keyPairs: new Map(),
+    } as IdbKeyServiceContext;
+
+    openIdbConnection(context);
+
+    context.getKeyPair = createGetKeyPair(context);
+
+    const safeAddKey = createSafeAddKey(context);
+    const safeHasKey = createSafeHasKey(context);
+    const safeRemoveKey = createSafeRemoveKey(context);
+    const safeClear = createSafeClear(context);
+    const safeSignTransaction = createSafeSignTransaction(context);
+
+    return result.ok({
+      addKey: asThrowable(safeAddKey),
+      hasKey: asThrowable(safeHasKey),
+      removeKey: asThrowable(safeRemoveKey),
+      clear: asThrowable(safeClear),
+      signTransaction: asThrowable(safeSignTransaction),
+      safeAddKey,
+      safeHasKey,
+      safeRemoveKey,
+      safeClear,
+      safeSignTransaction,
+    });
+  },
+);
+
+export const throwableCreateIdbKeyService: any = asThrowable(
+  safeCreateIdbKeyService,
+);

package/browser/src/idbKeyService/private/getKeyPair.ts

@@ -0,0 +1,39 @@
+import { safeKeyPair } from '@universal/index';
+import { result } from '@universal/src/_common/utils/result';
+import type { IdbKeyServiceContext } from '../idbKeyService';
+
+export const createGetKeyPair =
+  (context: IdbKeyServiceContext) =>
+  async (publicKey: any): Promise<any> => {
+    // 1. If the key pair is already in the cache, return it
+    if (context.keyPairs.has(publicKey))
+      return result.ok(context.keyPairs.get(publicKey));
+
+    if (!context.idb) return result.err(false); // TODO wait until idb is ready
+
+    // 2. Read the private key from the idb
+    const request = context.idb
+      .transaction('keyPairs', 'readonly')
+      .objectStore('keyPairs')
+      .get(publicKey);
+
+    return new Promise((resolve) => {
+      request.onsuccess = () => {
+        console.log('Key:', request.result);
+        if (!request.result) return resolve(result.err(false)); //Key.NotFound
+
+        // Try to create a key pair from the stored private key
+        const kp = safeKeyPair(request.result);
+        if (!kp.ok) return resolve(result.err(kp.error)); // Internal, should never happen
+
+        context.keyPairs.set(kp.value.publicKey, kp.value);
+        resolve(result.ok(kp.value));
+      };
+
+      // https://developer.mozilla.org/en-US/docs/Web/API/IDBObjectStore/get#exceptions
+      request.onerror = () => {
+        console.log('Error while getting key', request.error);
+        resolve(result.err(request.error)); // Internal
+      };
+    });
+  };

package/browser/src/idbKeyService/private/openIdbConnection.ts

@@ -0,0 +1,22 @@
+export const openIdbConnection = (context: any) => {
+  const dBOpenRequest = indexedDB.open(context.idbName, 1);
+
+  dBOpenRequest.onupgradeneeded = (event) => {
+    const idb = dBOpenRequest.result;
+    console.log('onupgradeneeded');
+    // Initialize Idb if it's not initialized yet
+    if (event.oldVersion === 0) {
+      idb.createObjectStore('keyPairs');
+    }
+  };
+
+  dBOpenRequest.onsuccess = () => {
+    console.log('onsuccess - 3');
+    context.idb = dBOpenRequest.result;
+  };
+
+  dBOpenRequest.onerror = () => {
+    console.log('onerror');
+    // Internal error
+  };
+};

package/browser/src/idbKeyService/public/addKey.ts

@@ -0,0 +1,32 @@
+import { keyPair } from '@universal/index';
+import { result } from '@universal/src/_common/utils/result';
+import type { IdbKeyServiceContext } from '../idbKeyService';
+
+export const createSafeAddKey =
+  (context: IdbKeyServiceContext) => async (args: any) => {
+    if (!context.idb) return result.err(false); // TODO wait until idb is ready
+
+    const kp = keyPair(args.privateKey);
+
+    // 2. Put the private key to the Idb
+    const request = context.idb
+      .transaction(['keyPairs'], 'readwrite')
+      .objectStore('keyPairs')
+      .put(kp.privateKey, kp.publicKey);
+
+    await new Promise((resolve, reject) => {
+      request.onsuccess = () => {
+        console.log('Key added', request.result);
+        context.keyPairs.set(kp.publicKey, kp);
+
+        resolve(result.ok(request.result));
+      };
+
+      request.onerror = () => {
+        console.log('Error while adding key', request.error);
+        reject(request.error);
+      };
+    });
+
+    return result.ok(kp);
+  };

package/browser/src/idbKeyService/public/clear.ts

@@ -0,0 +1,14 @@
+import { result } from '@universal/src/_common/utils/result';
+import type { IdbKeyServiceContext } from '../idbKeyService';
+
+export const createSafeClear = (context: IdbKeyServiceContext) => async () => {
+  if (!context.idb) return result.err(false); // TODO wait until idb is ready
+
+  const transaction = context.idb.transaction(['keyPairs'], 'readwrite');
+  const keyPairs = transaction.objectStore('keyPairs');
+
+  keyPairs.clear();
+  context.keyPairs.clear();
+
+  return result.ok(true);
+};

package/browser/src/idbKeyService/public/hasKey.ts

@@ -0,0 +1,9 @@
+import { result } from '@universal/src/_common/utils/result';
+import type { IdbKeyServiceContext } from '../idbKeyService';
+
+export const createSafeHasKey =
+  (context: IdbKeyServiceContext) => async (args: any) => {
+    const keyPair = await context.getKeyPair(args.publicKey);
+    /// TODO rework
+    return result.ok(keyPair.ok);
+  };

package/browser/src/idbKeyService/public/removeKey.ts

@@ -0,0 +1,26 @@
+import { result } from '@universal/src/_common/utils/result';
+import type { IdbKeyServiceContext } from '../idbKeyService';
+
+export const createSafeRemoveKey =
+  (context: IdbKeyServiceContext) =>
+  async (args: any): Promise<any> => {
+    if (!context.idb) return result.err(false); // TODO wait until idb is ready
+
+    const request = context.idb
+      .transaction('keyPairs', 'readwrite')
+      .objectStore('keyPairs')
+      .delete(args.publicKey);
+
+    return new Promise((resolve) => {
+      request.onsuccess = () => {
+        console.log('Key deleted', request.result);
+        context.keyPairs.delete(args.publicKey);
+        resolve(result.ok(request.result));
+      };
+
+      request.onerror = () => {
+        console.log('Error while deleting key', request.error);
+        resolve(result.err(request.error));
+      };
+    });
+  };

package/browser/src/idbKeyService/public/signTransaction.ts

@@ -0,0 +1,59 @@
+import { createNatError } from '@universal/src/_common/natError';
+import { TransactionSchema } from '@universal/src/_common/schemas/zod/transaction/transaction';
+import { getTransactionHash } from '@universal/src/_common/utils/getTransactionHash';
+import { result } from '@universal/src/_common/utils/result';
+import { wrapInternalError } from '@universal/src/_common/utils/wrapInternalError';
+import * as z from 'zod/mini';
+import type { IdbKeyServiceContext } from '../idbKeyService';
+
+const SignTransactionArgsSchema = z.object({
+  transaction: TransactionSchema,
+});
+
+export const createSafeSignTransaction: any = (context: IdbKeyServiceContext) =>
+  wrapInternalError(
+    `IdbKeyService.SignTransaction.Internal`,
+    async (args: any) => {
+      const validArgs = SignTransactionArgsSchema.safeParse(args);
+
+      if (!validArgs.success)
+        return result.err(
+          createNatError({
+            kind: `IdbKeyService.SignTransaction.Args.InvalidSchema`,
+            context: { zodError: validArgs.error },
+          }),
+        );
+
+      const { transaction: innerTransaction } = validArgs.data;
+
+      const keyPair = await context.getKeyPair(
+        innerTransaction.signerPublicKey.publicKey,
+      );
+
+      // TODO Think if it's possible to wrap into some helper function
+      if (!keyPair.ok) {
+        // if (keyPair.error.kind === 'MemoryKeyService.FindKeyPair.NotFound')
+        //   return result.err(
+        //     createNatError({
+        //       kind: 'MemoryKeyService.SignTransaction.SigningKeyPair.NotFound',
+        //       context: {
+        //         signerPublicKey: innerTransaction.signerPublicKey.publicKey,
+        //       },
+        //     }),
+        //   );
+        console.log(keyPair);
+        throw keyPair.error;
+      }
+
+      const { transactionHash, u8TransactionHash } =
+        getTransactionHash(innerTransaction);
+
+      const { signature } = keyPair.value.sign(u8TransactionHash); // todo make async?
+
+      return result.ok({
+        transaction: args.transaction,
+        transactionHash,
+        signature,
+      });
+    },
+  );

package/browser/types/idbKeyService/idbKeyService.ts

@@ -0,0 +1,7 @@
+import type { InternalErrorContext, InvalidSchemaErrorContext } from '@universal/types/natError';
+
+export interface IdbKeyServicePublicErrorRegister {
+  'CreateIdbKeyService.Internal': InternalErrorContext;
+  'IdbKeyService.SignTransaction.Args.InvalidSchema': InvalidSchemaErrorContext;
+  'IdbKeyService.SignTransaction.Internal': InternalErrorContext;
+}

package/browser/types/natError.ts

@@ -0,0 +1,5 @@
+import type { IdbKeyServicePublicErrorRegister } from './idbKeyService/idbKeyService';
+
+declare module '@universal/types/natError' {
+  interface NatPublicErrorRegistry extends IdbKeyServicePublicErrorRegister {}
+}