near-kit 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 r-near
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,375 @@
 # near-kit
+[![npm version](https://img.shields.io/npm/v/near-kit.svg)](https://www.npmjs.com/package/near-kit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)
 
-Reserved package name for a modern NEAR client toolkit.
+A simple, intuitive TypeScript library for interacting with NEAR Protocol. Designed to feel like a modern fetch library - easy for beginners, powerful for advanced users.
 
-> ⚠️ This is a placeholder publish. The API is under active design and may change without notice.
+**[📚 Full Documentation](https://kit.near.tools)**
 
+## Features
+
+- **Simple things should be simple** - One-line commands for common operations
+- **Type safety everywhere** - Full TypeScript support with IDE autocomplete
+- **Progressive complexity** - Basic API for simple needs, advanced features when required
+- **Powerful transaction builder** - Fluent, human-readable API for transactions
+- **Wallet-ready** - Full support for [HOT Connector](https://github.com/azbang/hot-connector) and [NEAR Wallet Selector](https://github.com/near/wallet-selector), drop-in integration
+
+## Installation
+
+```bash
+npm install near-kit
+# or
+bun install near-kit
+```
+
+## Quick Start
+
+```typescript
+import { Near } from 'near-kit';
+
+// Initialize with a private key for signing transactions
+const near = new Near({
+  network: 'testnet',
+  privateKey: 'ed25519:...',  // Your account's private key
+  defaultSignerId: 'alice.testnet'  // Default account for signing
+});
+
+// View a contract method (read-only, no gas)
+const balance = await near.view('example.testnet', 'get_balance', {
+  account_id: 'alice.testnet'
+});
+
+// Call a contract method (requires signature, costs gas)
+await near.call('example.testnet', 'increment', {}, {
+  attachedDeposit: '0.1'  // Attach 0.1 NEAR
+});
+
+// Send NEAR tokens
+await near.send('bob.testnet', '5');  // Send 5 NEAR to Bob
+
+// Check account balance
+const accountBalance = await near.getBalance('alice.testnet');
+console.log(accountBalance); // "100.00 NEAR"
+```
+
+## Core API
+
+### Initialization
+
+```typescript
+// Simple - defaults to mainnet
+const near = new Near();
+
+// With network selection
+const near = new Near({ network: 'testnet' });
+
+// With custom configuration
+const near = new Near({
+  network: 'testnet',
+  privateKey: 'ed25519:...',
+});
+```
+
+### Basic Operations
+
+```typescript
+// View methods (free, no signature required)
+const result = await near.view(
+  'contract.near',
+  'get_data',
+  { key: 'value' }
+);
+
+// Check account balance
+const balance = await near.getBalance('alice.near');
+
+// Check if account exists
+const exists = await near.accountExists('alice.near');
+
+// Get network status
+const status = await near.getStatus();
+```
+
+### Type-Safe Contracts
+
+```typescript
+import type { Contract } from 'near-kit';
+
+// Define contract interface using Contract<> helper
+type MyContract = Contract<{
+  view: {
+    get_balance: (args: { account_id: string }) => Promise<string>
+    get_info: () => Promise<{ name: string; version: string }>
+  }
+  call: {
+    // Just define args - options parameter automatically added!
+    transfer: (args: { to: string; amount: string }) => Promise<void>
+  }
+}>
+
+// Create type-safe contract
+const contract = near.contract<MyContract>('example.near');
+
+// Fully typed method calls
+const balance = await contract.view.get_balance({ account_id: 'alice.near' });
+const info = await contract.view.get_info();
+
+// Call methods automatically get options parameter
+await contract.call.transfer(
+  { to: 'bob.near', amount: '10' },
+  { attachedDeposit: '1 NEAR' }
+);
+```
+
+### Transaction Builder
+
+```typescript
+// Alice builds a transaction with multiple actions
+// 'alice.near' is the signer - the account that signs and pays for this transaction
+const receipt = await near.transaction('alice.near')  // Alice signs
+  .transfer('bob.near', '10')                         // Alice sends Bob 10 NEAR
+  .functionCall('market.near', 'buy', { id: '123' }, {
+    attachedDeposit: '5'                              // Alice attaches 5 NEAR to the call
+  })
+  .send();
+```
+
+### Batch Operations
+
+```typescript
+// Run multiple operations in parallel
+const [balance, status, exists] = await near.batch(
+  near.getBalance('alice.near'),
+  near.getStatus(),
+  near.accountExists('bob.near')
+);
+```
+
+## Local Testing with Sandbox
+
+```typescript
+import { Sandbox } from 'near-kit';
+
+const sandbox = await Sandbox.start();
+const near = new Near({ network: sandbox });
+// ... run tests
+await sandbox.stop();
+```
+
+**With test framework:**
+```typescript
+let sandbox: Sandbox;
+beforeAll(async () => { sandbox = await Sandbox.start(); });
+afterAll(async () => { await sandbox.stop(); });
+```
+
+## Key Management
+
+```typescript
+import { InMemoryKeyStore, FileKeyStore } from 'near-kit';
+
+// In-memory (runtime only)
+const near = new Near({
+  keyStore: new InMemoryKeyStore({
+    'alice.near': 'ed25519:...',
+  })
+});
+
+// File-based (persistent)
+const near = new Near({
+  keyStore: new FileKeyStore('~/.near-credentials')
+});
+```
+
+## Wallet Integration
+
+near-kit works seamlessly with popular NEAR wallets - just pass the wallet adapter and all methods will use the wallet for signing.
+
+### NEAR Wallet Selector
+
+```typescript
+import { Near, fromWalletSelector } from 'near-kit';
+import { setupWalletSelector } from '@near-wallet-selector/core';
+import { setupMyNearWallet } from '@near-wallet-selector/my-near-wallet';
+import { setupHereWallet } from '@near-wallet-selector/here-wallet';
+
+// Setup wallet selector
+const selector = await setupWalletSelector({
+  network: 'testnet',
+  modules: [
+    setupMyNearWallet(),
+    setupHereWallet(),
+  ],
+});
+
+// Get wallet instance (after user connects)
+const wallet = await selector.wallet();
+
+// Use with near-kit
+const near = new Near({
+  network: 'testnet',
+  wallet: fromWalletSelector(wallet),
+});
+
+// All operations now use the wallet for signing
+await near.call('contract.near', 'method', { arg: 'value' });
+await near.send('bob.near', '10');
+```
+
+### HOT Connector
+
+```typescript
+import { Near, fromHotConnect } from 'near-kit';
+import { NearConnector } from '@hot-labs/near-connect';
+
+// Create connector
+const connector = new NearConnector({ network: 'testnet' });
+
+// Wait for user to connect
+connector.on('wallet:signIn', async () => {
+  const near = new Near({
+    network: 'testnet',
+    wallet: fromHotConnect(connector),
+  });
+
+  // Use near-kit with the connected wallet
+  await near.call('contract.near', 'method', { arg: 'value' });
+});
+
+// Trigger wallet connection
+await connector.signIn();
+```
+
+## Error Handling
+
+```typescript
+import {
+  InsufficientBalanceError,
+  FunctionCallError,
+  NetworkError,
+} from 'near-kit';
+
+try {
+  await near.call('contract.near', 'method', {});
+} catch (error) {
+  if (error instanceof InsufficientBalanceError) {
+    console.log(`Need ${error.required}, have ${error.available}`);
+  } else if (error instanceof FunctionCallError) {
+    console.log(`Contract error: ${error.panic}`);
+  } else if (error instanceof NetworkError) {
+    // Retry logic
+  }
+}
+```
+
+## Advanced Features
+
+### Batch Actions (Multi-Action Transactions)
+
+Deploy and initialize a contract in a single transaction:
+
+```typescript
+const contractWasm = await fs.readFile('./contract.wasm');
+
+await near.transaction('alice.near')
+  .createAccount('contract.alice.near')
+  .transfer('contract.alice.near', '10 NEAR')
+  .deployContract('contract.alice.near', contractWasm)
+  .functionCall('contract.alice.near', 'init', { owner: 'alice.near' })
+  .send();
+```
+
+### NEP-413 Message Signing
+
+Authenticate users without gas fees:
+
+```typescript
+const signedMessage = await near.signMessage({
+  message: 'Login to MyApp',
+  recipient: 'myapp.near',
+  nonce: crypto.getRandomValues(new Uint8Array(32))
+});
+
+// Send to backend for verification
+await fetch('/api/auth', {
+  method: 'POST',
+  body: JSON.stringify(signedMessage)
+});
+```
+
+### Delegate Actions (NEP-366)
+
+Enable meta-transactions and sponsored transactions where a relayer pays the gas:
+
+```typescript
+// User creates and signs a delegate action (no gas cost to user)
+const userNear = new Near({
+  network: 'testnet',
+  privateKey: 'ed25519:...'  // User's key
+});
+
+const signedDelegateAction = await userNear
+  .transaction('user.near')
+  .transfer('recipient.near', '1 NEAR')
+  .delegate({ blockHeightOffset: 100 });
+
+// Relayer submits the transaction (pays the gas)
+const relayerNear = new Near({
+  network: 'testnet',
+  privateKey: 'ed25519:...'  // Relayer's key
+});
+
+await relayerNear
+  .transaction('relayer.near')
+  .signedDelegateAction(signedDelegateAction)
+  .send();
+```
+
+### Automatic Nonce Management
+
+No more nonce conflicts - the library handles nonce tracking and retries automatically:
+
+```typescript
+// Safe to run multiple transactions concurrently
+await Promise.all([
+  near.send('bob.near', '1'),
+  near.send('charlie.near', '1'),
+  near.send('dave.near', '1')
+]);
+// Nonces are automatically managed and conflicts are retried
+```
+
+### Smart Retry Logic
+
+Automatic retries for network errors with exponential backoff:
+
+```typescript
+try {
+  await near.call('contract.near', 'method', {});
+} catch (error) {
+  if (error instanceof TimeoutError && error.retryable) {
+    // Already retried automatically
+  }
+}
+```
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Run tests
+bun test
+
+# Build
+bun run build
+
+# Run examples
+bun run examples/basic-usage.ts
+```
+
+## License
+
+MIT

package/dist/contracts/contract.d.ts

@@ -0,0 +1,63 @@
+import type { Near } from "../core/near.js";
+import type { CallOptions } from "../core/types.js";
+/**
+ * Utility type to automatically add options parameter to call methods.
+ *
+ * Usage:
+ * ```typescript
+ * type MyContract = Contract<{
+ *   view: {
+ *     get_count: () => Promise<number>
+ *   }
+ *   call: {
+ *     increment: (args: { amount: number }) => Promise<void>
+ *   }
+ * }>
+ * ```
+ *
+ * The call method will automatically get an options parameter:
+ * increment: (args: { amount: number }, options?: CallOptions) => Promise<void>
+ */
+export type Contract<T extends {
+    view: Record<string, (...args: any[]) => any>;
+    call: Record<string, (...args: any[]) => any>;
+}> = {
+    view: T["view"];
+    call: {
+        [K in keyof T["call"]]: T["call"][K] extends (...args: infer TArgs) => infer TReturn ? TArgs extends [infer TFirstArg, ...infer _Rest] ? (args: TFirstArg, options?: CallOptions) => TReturn : (args?: undefined, options?: CallOptions) => TReturn : never;
+    };
+};
+/**
+ * Base contract method interface used by {@link Contract}.
+ *
+ * Methods can be defined as:
+ * - View methods: (args?: ArgsType | Uint8Array, options?: BlockReference) => Promise<ReturnType>
+ * - Call methods: (args?: ArgsType | Uint8Array, options?: CallOptions) => Promise<ReturnType>
+ *
+ * This is a base interface without index signatures to allow
+ * extending interfaces to define specific method signatures with type safety.
+ */
+export interface ContractMethods {
+    view: Record<string, (...args: any[]) => Promise<any>>;
+    call: Record<string, (...args: any[]) => Promise<any>>;
+}
+/**
+ * Create a type-safe contract proxy for a NEAR contract.
+ *
+ * @param near - The {@link Near} client instance to use for calls.
+ * @param contractId - Account ID of the target contract.
+ *
+ * @returns A proxy implementing the given {@link ContractMethods} interface.
+ *
+ * @remarks
+ * Prefer using {@link Near.contract} instead of calling this function directly.
+ */
+export declare function createContract<T extends ContractMethods>(near: Near, contractId: string): T;
+/**
+ * Helper to extend {@link Near} prototype with a `contract` method.
+ *
+ * @internal This is used to keep the core {@link Near} implementation focused;
+ * library users should call {@link Near.contract} instead of using this helper.
+ */
+export declare function addContractMethod(nearPrototype: typeof Near.prototype): void;
+//# sourceMappingURL=contract.d.ts.map

package/dist/contracts/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../src/contracts/contract.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAA;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAEnD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,QAAQ,CAClB,CAAC,SAAS;IAER,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,CAAA;IAE7C,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,CAAA;CAC9C,IACC;IACF,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAA;IACf,IAAI,EAAE;SACH,CAAC,IAAI,MAAM,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAC3C,GAAG,IAAI,EAAE,MAAM,KAAK,KACjB,MAAM,OAAO,GACd,KAAK,SAAS,CAAC,MAAM,SAAS,EAAE,GAAG,MAAM,KAAK,CAAC,GAC7C,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,WAAW,KAAK,OAAO,GACnD,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,WAAW,KAAK,OAAO,GACtD,KAAK;KACV,CAAA;CACF,CAAA;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAE9B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC,CAAA;IAEtD,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC,CAAA;CACvD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,eAAe,EACtD,IAAI,EAAE,IAAI,EACV,UAAU,EAAE,MAAM,GACjB,CAAC,CAiCH;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,OAAO,IAAI,CAAC,SAAS,GAAG,IAAI,CAO5E"}

package/dist/contracts/contract.js

@@ -0,0 +1,42 @@
+/**
+ * Create a type-safe contract proxy for a NEAR contract.
+ *
+ * @param near - The {@link Near} client instance to use for calls.
+ * @param contractId - Account ID of the target contract.
+ *
+ * @returns A proxy implementing the given {@link ContractMethods} interface.
+ *
+ * @remarks
+ * Prefer using {@link Near.contract} instead of calling this function directly.
+ */
+export function createContract(near, contractId) {
+    const proxy = {
+        view: new Proxy({}, {
+            get: (_target, methodName) => {
+                return async (args, options) => {
+                    return await near.view(contractId, methodName, args || {}, options);
+                };
+            },
+        }),
+        call: new Proxy({}, {
+            get: (_target, methodName) => {
+                return async (args, options) => {
+                    return await near.call(contractId, methodName, args || {}, options || {});
+                };
+            },
+        }),
+    };
+    return proxy;
+}
+/**
+ * Helper to extend {@link Near} prototype with a `contract` method.
+ *
+ * @internal This is used to keep the core {@link Near} implementation focused;
+ * library users should call {@link Near.contract} instead of using this helper.
+ */
+export function addContractMethod(nearPrototype) {
+    nearPrototype.contract = function (contractId) {
+        return createContract(this, contractId);
+    };
+}
+//# sourceMappingURL=contract.js.map

package/dist/contracts/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../src/contracts/contract.ts"],"names":[],"mappings":"AA2DA;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAC5B,IAAU,EACV,UAAkB;IAElB,MAAM,KAAK,GAAG;QACZ,IAAI,EAAE,IAAI,KAAK,CACb,EAAE,EACF;YACE,GAAG,EAAE,CAAC,OAAO,EAAE,UAAkB,EAAE,EAAE;gBACnC,OAAO,KAAK,EACV,IAA0B,EAC1B,OAAwB,EACxB,EAAE;oBACF,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,UAAU,EAAE,IAAI,IAAI,EAAE,EAAE,OAAO,CAAC,CAAA;gBACrE,CAAC,CAAA;YACH,CAAC;SACF,CACF;QACD,IAAI,EAAE,IAAI,KAAK,CACb,EAAE,EACF;YACE,GAAG,EAAE,CAAC,OAAO,EAAE,UAAkB,EAAE,EAAE;gBACnC,OAAO,KAAK,EAAE,IAA0B,EAAE,OAAqB,EAAE,EAAE;oBACjE,OAAO,MAAM,IAAI,CAAC,IAAI,CACpB,UAAU,EACV,UAAU,EACV,IAAI,IAAI,EAAE,EACV,OAAO,IAAI,EAAE,CACd,CAAA;gBACH,CAAC,CAAA;YACH,CAAC;SACF,CACF;KACF,CAAA;IAED,OAAO,KAAU,CAAA;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,aAAoC;IACpE,aAAa,CAAC,QAAQ,GAAG,UAEvB,UAAkB;QAElB,OAAO,cAAc,CAAI,IAAI,EAAE,UAAU,CAAC,CAAA;IAC5C,CAAC,CAAA;AACH,CAAC"}

package/dist/contracts/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Contract interfaces and utilities
+ */
+export * from "./contract.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/contracts/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/contracts/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,eAAe,CAAA"}

package/dist/contracts/index.js

@@ -0,0 +1,5 @@
+/**
+ * Contract interfaces and utilities
+ */
+export * from "./contract.js";
+//# sourceMappingURL=index.js.map

package/dist/contracts/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/contracts/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,eAAe,CAAA"}