https://github.com/elliotbraem/web4-api-js
Simple client library for apps deployed to web4
https://github.com/elliotbraem/web4-api-js
near web4
Last synced: 9 months ago
JSON representation
Simple client library for apps deployed to web4
- Host: GitHub
- URL: https://github.com/elliotbraem/web4-api-js
- Owner: elliotBraem
- License: mit
- Created: 2025-02-12T02:53:53.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-02-12T03:11:34.000Z (11 months ago)
- Last Synced: 2025-03-30T03:34:58.799Z (10 months ago)
- Topics: near, web4
- Language: TypeScript
- Homepage:
- Size: 11.7 KB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# web4-api-js
Simple client library for authentication, view method calls, and contracts calls for apps deployed to [web4](https://web4.near.page/).
* /web4/login → `login()`
* /web4/logout → `logout()`
* `GET` /web4/contract/{contract_id}/{method_name} → `await view()`
* `POST` /web4/contract/{contract_id}/{method_name} → `await call()`
To see it in action or deploy your own profile to web4, try out [this example](https://github.com/NEARBuilders/profile).
## Installation
```bash
npm install web4-api-js
# or
yarn add web4-api-js
# or
bun add web4-api-js
```
## Usage
```typescript
import { login, logout, isSignedIn, getAccountId, view, call } from 'web4-api-js';
// Authentication
if (!isSignedIn()) {
login({
contractId: 'example.near',
callbackPath: '/dashboard'
});
}
const accountId = getAccountId();
console.log('Logged in as:', accountId);
// View method (read-only)
const balance = await view(
'token.near',
'ft_balance_of',
{ account_id: accountId }
);
// Call method
await call(
'token.near',
'ft_transfer',
{
receiver_id: 'bob.near',
amount: '1000000000000000000000000'
},
{
deposit: '1', // in yoctoNEAR
gas: '100000000000000', // 100 TGas
callbackUrl: '/transfer/success'
}
);
// Logout
logout();
```
## API Reference
### Authentication
#### `login(options?: LoginOptions): void`
Initiates the web4 login process by redirecting to global login page
- `options.contractId`: Contract requiring access (optional)
- `options.callbackPath`: Path to return to after login (optional)
#### `logout(): void`
Logs out the current user and clears web4 session data.
#### `isSignedIn(): boolean`
Checks if a user is currently signed in.
#### `getAccountId(): string | undefined`
Gets the currently signed in account ID.
#### `getSessionKey(): string | undefined`
Gets the current session's private key.
### Contract Interaction
#### `view(contractId: string, methodName: string, args?: ViewMethodArgs): Promise`
Calls a view method on a web4 contract.
- `contractId`: The contract to call
- `methodName`: The view method to call
- `args`: Arguments to pass to the method (optional)
- Returns: Promise resolving to the method's return value
#### `call(contractId: string, methodName: string, args: ContractCallArgs, options?: ContractCallOptions): Promise`
Calls a method on a web4 contract that can modify state.
- `contractId`: The contract to call
- `methodName`: The method to call
- `args`: Arguments to pass to the method
- `options`: Optional call configuration
- `gas`: Gas limit for the transaction
- `deposit`: Amount of NEAR to attach to the call
- `callbackUrl`: URL to return to after transaction completion
- Returns: Promise resolving to the execution outcome or redirects for signing
## Contributing
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.
