near-kit 0.0.0 → 0.2.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,477 @@
 # near-kit
 
-Reserved package name for a modern NEAR client toolkit.
+[![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/)
 
-> ⚠️ This is a placeholder publish. The API is under active design and may change without notice.
+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.
 
+**[📚 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 for backend/scripts
+const near = new Near({
+  network: "testnet",
+  privateKey: "ed25519:...",
+  defaultSignerId: "alice.testnet",
+})
+
+// View methods (read-only, no gas)
+const balance = await near.view("example.testnet", "get_balance", {
+  account_id: "alice.testnet",
+})
+
+// Call methods (requires signature, costs gas)
+await near.call(
+  "example.testnet",
+  "increment",
+  {},
+  {attachedDeposit: "0.1 NEAR"}
+)
+
+// Send NEAR tokens
+await near.send("bob.testnet", "5 NEAR")
+```
+
+## Getting Started
+
+near-kit provides a unified API that works across different environments. Configuration varies by environment, but the API for calling contracts, sending transactions, and building transactions remains identical.
+
+### Backend & Scripts
+
+For local testing, use the sandbox (no network or key configuration needed):
+
+```typescript
+import { Sandbox } from "near-kit"
+
+const sandbox = await Sandbox.start()
+const near = new Near({ network: sandbox })
+
+// Test with automatically provisioned accounts
+await near.call("contract.test.near", "method", {})
+
+await sandbox.stop()
+```
+
+For testnet/mainnet development, pass a private key directly:
+
+```typescript
+const near = new Near({
+  network: "testnet",
+  privateKey: "ed25519:...",
+  defaultSignerId: "alice.testnet",
+})
+```
+
+For production applications, use a keyStore:
+
+```typescript
+import { FileKeyStore } from "near-kit"
+
+const near = new Near({
+  network: "testnet",
+  keyStore: new FileKeyStore("~/.near-credentials"),
+})
+```
+
+### Frontend & Wallets
+
+In the browser, connect to user wallets. The same `near.call()`, `near.send()`, and `near.transaction()` methods work seamlessly:
+
+```typescript
+import { fromWalletSelector } from "near-kit"
+
+const near = new Near({
+  network: "testnet",
+  wallet: fromWalletSelector(walletInstance),
+})
+
+// Same API as backend
+await near.call("contract.near", "method", { arg: "value" })
+```
+
+This works through a signer abstraction - whether you pass `privateKey`, `keyStore`, `wallet`, or `sandbox`, they all implement the same signing interface internally.
+
+## 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 NEAR") // Alice sends Bob 10 NEAR
+  .functionCall(
+    "market.near",
+    "buy",
+    { id: "123" },
+    { attachedDeposit: "5 NEAR" } // 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, RotatingKeyStore } 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"),
+})
+
+// Rotating keys for high-throughput concurrent transactions
+const near = new Near({
+  keyStore: new RotatingKeyStore({
+    "alice.near": [
+      "ed25519:key1...",
+      "ed25519:key2...",
+      "ed25519:key3...",
+    ],
+  }),
+})
+```
+
+## Wallet Integration
+
+near-kit integrates with Wallet Selector and HOT Connector through a signer abstraction. Wallet adapters are converted to signers via `fromWalletSelector()` and `fromHotConnect()` shims, allowing the same API to work across backend and frontend without separate client implementations.
+
+### 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 NEAR")
+```
+
+### 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
+
+Errors are organized by category and include detailed context for debugging. Use `instanceof` checks to handle specific error types.
+
+#### Network Errors
+
+```typescript
+import { NetworkError, TimeoutError } from "near-kit"
+
+try {
+  await near.call("contract.near", "method", {})
+} catch (error) {
+  if (error instanceof TimeoutError) {
+    console.log("Request timed out - already retried automatically")
+  } else if (error instanceof NetworkError) {
+    // Handle other network issues
+  }
+}
+```
+
+#### Transaction Errors
+
+```typescript
+import { InsufficientBalanceError, InvalidNonceError } from "near-kit"
+
+try {
+  await near.send("bob.near", "1000000 NEAR")
+} catch (error) {
+  if (error instanceof InsufficientBalanceError) {
+    console.log(`Need ${error.required}, have ${error.available}`)
+  } else if (error instanceof InvalidNonceError) {
+    // Already retried automatically - only thrown if retries exhausted
+  }
+}
+```
+
+#### Contract Errors
+
+```typescript
+import { FunctionCallError } from "near-kit"
+
+try {
+  await near.call("contract.near", "method", {})
+} catch (error) {
+  if (error instanceof FunctionCallError) {
+    console.log(`Contract panicked: ${error.panic}`)
+    console.log(`Logs:`, error.logs)
+  }
+}
+```
+
+## 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"),
+  near.send("charlie.near", "1 NEAR"),
+  near.send("dave.near", "1 NEAR"),
+])
+// 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/quickstart.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"}