near-kit 0.0.0 → 0.2.0

package/dist/core/transaction.d.ts

@@ -0,0 +1,390 @@
+/**
+ * Fluent API for building and sending NEAR transactions.
+ *
+ * Allows chaining multiple actions (transfers, function calls, account creation, etc.)
+ * into a single atomic transaction. All actions either succeed together or fail together.
+ *
+ * The builder is created via {@link Near.transaction} with a signer account ID. This
+ * account must have signing credentials available (via keyStore, privateKey, custom
+ * signer, or wallet connection).
+ *
+ * @example
+ * ```typescript
+ * // Single action
+ * await near.transaction('alice.near')
+ *   .transfer('bob.near', '10 NEAR')
+ *   .send()
+ *
+ * // Multiple actions (atomic)
+ * await near.transaction('alice.near')
+ *   .createAccount('sub.alice.near')
+ *   .transfer('sub.alice.near', '5 NEAR')
+ *   .addKey(newKey, { type: 'fullAccess' })
+ *   .send()
+ * ```
+ *
+ * @remarks
+ * - The `signerId` (set via `Near.transaction()`) is the account that signs and pays for gas
+ * - All actions execute in the order they are added
+ * - Transaction is only sent when `.send()` is called
+ * - Use `.build()` to get unsigned transaction
+ */
+import { type Amount, type Gas, type PrivateKey } from "../utils/validation.js";
+import type { RpcClient } from "./rpc/rpc.js";
+import { type SignedDelegateAction } from "./schema.js";
+import type { FinalExecutionOutcomeMap, KeyStore, PublicKey, SendOptions, Signer, Transaction, TxExecutionStatus, WalletConnection } from "./types.js";
+/**
+ * User-friendly access key permission format
+ */
+export type AccessKeyPermission = {
+    type: "fullAccess";
+} | {
+    type: "functionCall";
+    receiverId: string;
+    methodNames?: string[];
+    allowance?: Amount;
+};
+type DelegateSigningOptions = {
+    receiverId?: string;
+    /**
+     * Explicit block height at which the delegate action expires.
+     * If omitted, uses the current block height plus `blockHeightOffset`.
+     */
+    maxBlockHeight?: bigint;
+    /**
+     * Number of blocks after the current height when the delegate action should expire.
+     * Defaults to 200 blocks if neither this nor `maxBlockHeight` is provided.
+     */
+    blockHeightOffset?: number;
+    /**
+     * Override nonce to use for the delegate action. If omitted, the builder fetches
+     * the access key and uses (nonce + 1).
+     */
+    nonce?: bigint;
+    /**
+     * Explicit public key to embed in the delegate action. Only required when the key
+     * cannot be resolved from the configured key store.
+     */
+    publicKey?: string | PublicKey;
+};
+/**
+ * Fluent builder for constructing and sending NEAR transactions.
+ *
+ * Created via {@link Near.transaction}. Supports chaining multiple actions
+ * (transfers, function calls, key management, staking, delegate actions) into
+ * a single atomic transaction.
+ */
+export declare class TransactionBuilder {
+    private static nonceManager;
+    private signerId;
+    private actions;
+    private receiverId?;
+    private rpc;
+    private keyStore;
+    private signer?;
+    private keyPair?;
+    private wallet?;
+    private defaultWaitUntil;
+    private ensureKeyStoreReady?;
+    private cachedSignedTx?;
+    constructor(signerId: string, rpc: RpcClient, keyStore: KeyStore, signer?: Signer, defaultWaitUntil?: TxExecutionStatus, wallet?: WalletConnection, ensureKeyStoreReady?: () => Promise<void>);
+    /**
+     * Invalidate cached signed transaction when builder state changes
+     */
+    private invalidateCache;
+    /**
+     * Resolve the key pair for the current signer from either `signWith()` or keyStore.
+     */
+    private resolveKeyPair;
+    /**
+     * Add a token transfer action.
+     *
+     * @param receiverId - Account ID that will receive the tokens.
+     * @param amount - Amount to transfer, expressed as {@link Amount} (e.g. `"10 NEAR"`).
+     *
+     * @returns This builder instance for chaining.
+     *
+     * @remarks
+     * If no receiver has been set yet, this also sets the transaction `receiverId`
+     * to `receiverId`.
+     */
+    transfer(receiverId: string, amount: Amount): this;
+    /**
+     * Add a function call action.
+     *
+     * @param contractId - Account ID of the target contract.
+     * @param methodName - Name of the change method to call.
+     * @param args - Arguments object or raw bytes; defaults to `{}`.
+     * @param options - Optional gas and attached deposit settings.
+     *
+     * @returns This builder instance for chaining.
+     *
+     * @remarks
+     * - `options.gas` accepts human-readable values such as `"30 Tgas"` or {@link Gas.Tgas}.
+     * - `options.attachedDeposit` uses {@link Amount} semantics (e.g. `"1 yocto"`).
+     * - If no receiver has been set yet, this also sets the transaction `receiverId`
+     *   to `contractId`.
+     */
+    functionCall(contractId: string, methodName: string, args?: object | Uint8Array, options?: {
+        gas?: Gas;
+        attachedDeposit?: Amount;
+    }): this;
+    /**
+     * Add a create account action
+     */
+    createAccount(accountId: string): this;
+    /**
+     * Add a delete account action
+     */
+    deleteAccount(beneficiaryId: string): this;
+    /**
+     * Add a deploy contract action
+     */
+    deployContract(accountId: string, code: Uint8Array): this;
+    /**
+     * Publish a global contract that can be reused by multiple accounts
+     *
+     * @param code - The compiled contract code bytes
+     * @param publisherId - Optional account ID. If provided, creates a mutable contract (can be updated).
+     *                      If omitted, creates an immutable contract (identified by code hash).
+     *
+     * @example
+     * ```typescript
+     * // Publish immutable contract (identified by code hash)
+     * await near.transaction(accountId)
+     *   .publishContract(contractCode)
+     *   .send()
+     *
+     * // Publish mutable contract (identified by account, can be updated)
+     * await near.transaction(accountId)
+     *   .publishContract(contractCode, "my-publisher.near")
+     *   .send()
+     * ```
+     */
+    publishContract(code: Uint8Array, publisherId?: string): this;
+    /**
+     * Deploy a contract to this account from previously published code in the global registry
+     *
+     * @param reference - Reference to the published contract, either:
+     *                    - { codeHash: Uint8Array | string } - Reference by code hash (Uint8Array or base58 string)
+     *                    - { accountId: string } - Reference by the account that published it
+     *
+     * @example
+     * ```typescript
+     * // Deploy from code hash (Uint8Array)
+     * await near.transaction(accountId)
+     *   .deployFromPublished({ codeHash: hashBytes })
+     *   .send()
+     *
+     * // Deploy from code hash (base58 string)
+     * await near.transaction(accountId)
+     *   .deployFromPublished({ codeHash: "5FzD8..." })
+     *   .send()
+     *
+     * // Deploy from account ID
+     * await near.transaction(accountId)
+     *   .deployFromPublished({ accountId: "contract-publisher.near" })
+     *   .send()
+     * ```
+     */
+    deployFromPublished(reference: {
+        codeHash: string | Uint8Array;
+    } | {
+        accountId: string;
+    }): this;
+    /**
+     * Add a stake action
+     */
+    stake(publicKey: string, amount: Amount): this;
+    /**
+     * Add an add key action
+     *
+     * The key is added to the receiverId of the transaction.
+     * If receiverId is not set, it defaults to signerId.
+     */
+    addKey(publicKey: string, permission: AccessKeyPermission): this;
+    /**
+     * Add a delete key action
+     */
+    deleteKey(accountId: string, publicKey: string): this;
+    /**
+     * Build and sign a delegate action from the queued actions.
+     *
+     * @param options - Optional overrides for receiver, nonce, and expiration
+     */
+    /**
+     * Add a signed delegate action to this transaction (for relayers).
+     */
+    signedDelegateAction(signedDelegate: SignedDelegateAction): this;
+    /**
+     * Build and sign a delegate action from the queued actions.
+     *
+     * @returns Signed delegate action ready to be added to a relayer transaction
+     */
+    delegate(options?: DelegateSigningOptions): Promise<SignedDelegateAction>;
+    /**
+     * Override the signing function for this specific transaction.
+     *
+     * Use this to sign with a different signer than the one configured in the
+     * Near client, while keeping the same signerId. Useful for:
+     *
+     * - Using a hardware wallet for a specific transaction
+     * - Testing with mock signers
+     * - Signing with a specific private key for the same account
+     * - One-off custom signing logic
+     *
+     * **Important:** This overrides HOW the transaction is signed, not WHO signs it.
+     * The signerId (set via `.transaction()`) remains the same. To sign as a different
+     * account, use `.transaction(otherAccountId)` instead.
+     *
+     * @param key - Either a custom signer function or a private key string
+     *              (e.g., 'ed25519:...' or 'secp256k1:...')
+     *              Type-safe: TypeScript will enforce the correct format at compile time
+     * @returns This builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * // Override with different hardware wallet
+     * await near.transaction('alice.near')
+     *   .signWith(aliceHardwareWallet)
+     *   .transfer('bob.near', '5 NEAR')
+     *   .send()
+     *
+     * // Sign with specific ed25519 private key (type-safe)
+     * await near.transaction('alice.near')
+     *   .signWith('ed25519:...')  // ✅ TypeScript ensures correct format
+     *   .transfer('bob.near', '1 NEAR')
+     *   .send()
+     *
+     * // Sign with specific secp256k1 private key
+     * await near.transaction('alice.near')
+     *   .signWith('secp256k1:...')  // ✅ TypeScript ensures correct format
+     *   .transfer('bob.near', '1 NEAR')
+     *   .send()
+     *
+     * // TypeScript will catch mistakes at compile time:
+     * await near.transaction('alice.near')
+     *   .signWith('alice.near')  // ❌ Type error: not a PrivateKey
+     *
+     * // Mock signer for testing
+     * const mockSigner: Signer = async (msg) => ({
+     *   keyType: KeyType.ED25519,
+     *   data: new Uint8Array(64)
+     * })
+     *
+     * await near.transaction('test.near')
+     *   .signWith(mockSigner)
+     *   .transfer('receiver.near', '1')
+     *   .send()
+     * ```
+     *
+     * @remarks
+     * Supports both ed25519 and secp256k1 keys.
+     */
+    signWith(key: PrivateKey | Signer): this;
+    /**
+     * Build the unsigned transaction
+     */
+    build(): Promise<Transaction>;
+    /**
+     * Sign the transaction without sending it.
+     *
+     * This creates a signed transaction that can be:
+     * - Inspected via `getHash()`
+     * - Serialized via `serialize()`
+     * - Sent later via `send()`
+     *
+     * The signed transaction is cached internally. If you modify the transaction
+     * (add actions, change signer, etc.), the cache is automatically invalidated.
+     *
+     * @returns This builder instance (now in a signed state)
+     *
+     * @example
+     * ```typescript
+     * // Sign and inspect hash
+     * const tx = await near.transaction('alice.near')
+     *   .transfer('bob.near', '1 NEAR')
+     *   .sign()
+     *
+     * console.log('Transaction hash:', tx.getHash())
+     *
+     * // Serialize for offline use
+     * const bytes = tx.serialize()
+     *
+     * // Send when ready
+     * const result = await tx.send({ waitUntil: 'FINAL' })
+     * ```
+     */
+    sign(): Promise<this>;
+    /**
+     * Get the transaction hash (only available after signing).
+     *
+     * @returns The base58-encoded transaction hash, or null if not yet signed
+     *
+     * @example
+     * ```typescript
+     * const tx = await near.transaction('alice.near')
+     *   .transfer('bob.near', '1 NEAR')
+     *   .sign()
+     *
+     * console.log(tx.getHash()) // "8ZQ7..."
+     * ```
+     */
+    getHash(): string | null;
+    /**
+     * Serialize the signed transaction to bytes.
+     *
+     * This is useful for:
+     * - Storing signed transactions for later broadcast
+     * - Sending transactions through external tools
+     * - Multi-sig workflows
+     *
+     * @returns Borsh-serialized signed transaction bytes
+     * @throws {NearError} If transaction has not been signed yet
+     *
+     * @example
+     * ```typescript
+     * const tx = await near.transaction('alice.near')
+     *   .transfer('bob.near', '1 NEAR')
+     *   .sign()
+     *
+     * const bytes = tx.serialize()
+     * fs.writeFileSync('transaction.bin', bytes)
+     * ```
+     */
+    serialize(): Uint8Array;
+    /**
+     * Sign and send the transaction
+     *
+     * If the transaction has already been signed (via `.sign()`), it will use the
+     * cached signed transaction. Otherwise, it will sign the transaction automatically.
+     *
+     * The response will always include `transaction.hash` for tracking, even when
+     * using `waitUntil: "NONE"` which normally doesn't return transaction details.
+     *
+     * @param options - Optional configuration for sending the transaction
+     * @param options.waitUntil - Controls when the RPC returns after submitting the transaction
+     * @returns Promise resolving to the final execution outcome
+     *
+     * @example
+     * ```typescript
+     * // Use default wait until
+     * await near.transaction(account).transfer(receiver, "1 NEAR").send()
+     *
+     * // Wait for full finality
+     * await near.transaction(account)
+     *   .transfer(receiver, "1 NEAR")
+     *   .send({ waitUntil: "FINAL" })
+     *
+     * // Fire and forget with NONE - hash still available
+     * const result = await near.transaction(account)
+     *   .transfer(receiver, "1 NEAR")
+     *   .send({ waitUntil: "NONE" })
+     * console.log(result.transaction.hash) // Always available!
+     * ```
+     */
+    send(): Promise<FinalExecutionOutcomeMap["EXECUTED_OPTIMISTIC"]>;
+    send<W extends keyof FinalExecutionOutcomeMap>(options: SendOptions<W>): Promise<FinalExecutionOutcomeMap[W]>;
+}
+export {};
+//# sourceMappingURL=transaction.d.ts.map

package/dist/core/transaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../../src/core/transaction.ts"],"names":[],"mappings":"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"}