Oviato SDK

Installation & Setup

Install and configure @oviato/sdk in your JavaScript project

This guide covers installing and setting up @oviato/sdk in any JavaScript framework or vanilla JS project.

Prerequisites

Before you begin:

An Oviato App ID - Create one at dashboard.oviato.com
- See Setting Up Your App for instructions
Node.js 16+ installed (for NPM installation)
A JavaScript project (or just an HTML file for CDN usage)

Installation Options

Option 1: NPM (Recommended)

For modern JavaScript projects with a build system:

# npm
npm install @oviato/sdk

# pnpm
pnpm add @oviato/sdk

# yarn
yarn add @oviato/sdk

# bun
bun add @oviato/sdk

Option 2: CDN

For quick prototyping or simple HTML projects:

<!DOCTYPE html>
<html>
  <head>
    <title>My App</title>
  </head>
  <body>
    <button id="connect-btn">Connect Wallet</button>
    <div id="status"></div>

    <script src="https://cdn.jsdelivr.net/npm/@oviato/sdk@latest/dist/oviato.min.js"></script>
    <script>
      const { initialize, authenticate, getSession } = OviatoSDK;

      // Your code here
    </script>
  </body>
</html>

Basic Setup

1. Initialize the SDK

Initialize the SDK before using any other functions:

import { initialize } from "@oviato/sdk";

await initialize({
  appId: "your-app-id",
  network: "bitcoinmainnet", // optional, default: 'bitcoinmainnet'
  env: "prod", // optional, default: 'prod'
});

2. Authenticate Users

Use the smart authenticate() function to handle both new and returning users:

import { authenticate } from "@oviato/sdk";

const result = await authenticate({
  username: "alice", // optional: pre-fill username
});

if (result.status === "success") {
  console.log("Connected!");
  console.log("Address:", result.data.address);
  console.log("Username:", result.data.username);
}

3. Access Session Data

import { getSession, isAuthenticated } from "@oviato/sdk";

const session = getSession();
if (session) {
  console.log("User is connected:", session.address);
}

const isAuth = isAuthenticated(); // true/false

Framework-Specific Setup

Vanilla JavaScript

<!DOCTYPE html>
<html>
  <body>
    <div id="app">
      <button id="connect">Connect Wallet</button>
      <div id="status"></div>
    </div>

    <script type="module">
      import {
        initialize,
        authenticate,
        getSession,
        clearSession,
      } from "https://cdn.jsdelivr.net/npm/@oviato/sdk@latest/+esm";

      // Initialize
      await initialize({
        appId: "your-app-id",
        network: "bitcoinmainnet",
      });

      // Connect button
      document.getElementById("connect").onclick = async () => {
        const result = await authenticate();

        if (result.status === "success") {
          updateStatus();
        }
      };

      function updateStatus() {
        const session = getSession();
        const statusDiv = document.getElementById("status");

        if (session) {
          statusDiv.innerHTML = `
          <p>Connected: ${session.address}</p>
          <p>Username: ${session.username}</p>
          <button onclick="handleDisconnect()">Disconnect</button>
        `;
          document.getElementById("connect").style.display = "none";
        }
      }

      window.handleDisconnect = () => {
        clearSession();
        location.reload();
      };

      // Check on load
      updateStatus();
    </script>
  </body>
</html>

Vue 3 (Composition API)

<script setup>
import { ref, onMounted, onUnmounted } from "vue";
import { oviStore, initialize, authenticate, clearSession } from "@oviato/sdk";

const session = ref(null);
const isLoading = ref(true);
let unsubscribe;

onMounted(async () => {
  // Initialize SDK
  await initialize({
    appId: import.meta.env.VITE_OVIATO_APP_ID,
    network: "bitcoinmainnet",
  });

  // Subscribe to state changes
  unsubscribe = oviStore.subscribe((state) => {
    session.value = state.session;
    isLoading.value = state.isLoading;
  });

  // Get initial state
  const state = oviStore.getState();
  session.value = state.session;
  isLoading.value = state.isLoading;
});

onUnmounted(() => {
  unsubscribe?.();
});

const handleConnect = async () => {
  const result = await authenticate();
  if (result.status === "success") {
    console.log("Connected!");
  }
};

const handleDisconnect = () => {
  clearSession();
};
</script>

<template>
  <div>
    <div v-if="isLoading">Loading...</div>

    <div v-else-if="session">
      <h2>Welcome, {{ session.username }}!</h2>
      <p>Address: {{ session.address }}</p>
      <p>Network: {{ session.network }}</p>
      <button @click="handleDisconnect">Disconnect</button>
    </div>

    <div v-else>
      <button @click="handleConnect">Connect Wallet</button>
    </div>
  </div>
</template>

Svelte

<script>
import { onMount, onDestroy } from 'svelte';
import { oviStore, initialize, authenticate, clearSession } from '@oviato/sdk';

let session = null;
let isLoading = true;
let unsubscribe;

onMount(async () => {
  // Initialize SDK
  await initialize({
    appId: import.meta.env.VITE_OVIATO_APP_ID,
    network: 'bitcoinmainnet',
  });

  // Subscribe to state changes
  unsubscribe = oviStore.subscribe((state) => {
    session = state.session;
    isLoading = state.isLoading;
  });

  // Get initial state
  const state = oviStore.getState();
  session = state.session;
  isLoading = state.isLoading;
});

onDestroy(() => {
  unsubscribe?.();
});

const handleConnect = async () => {
  const result = await authenticate();
  if (result.status === 'success') {
    console.log('Connected!');
  }
};

const handleDisconnect = () => {
  clearSession();
};
</script>

{#if isLoading}
  <p>Loading...</p>
{:else if session}
  <div>
    <h2>Welcome, {session.username}!</h2>
    <p>Address: {session.address}</p>
    <p>Network: {session.network}</p>
    <button on:click={handleDisconnect}>Disconnect</button>
  </div>
{:else}
  <button on:click={handleConnect}>Connect Wallet</button>
{/if}

Angular

// app.component.ts
import { Component, OnInit, OnDestroy } from "@angular/core";
import { oviStore, initialize, authenticate, clearSession } from "@oviato/sdk";
import type { UserSession } from "@oviato/sdk";

@Component({
  selector: "app-root",
  template: `
    <div *ngIf="isLoading">Loading...</div>

    <div *ngIf="!isLoading && session">
      <h2>Welcome, {{ session.username }}!</h2>
      <p>Address: {{ session.address }}</p>
      <button (click)="handleDisconnect()">Disconnect</button>
    </div>

    <div *ngIf="!isLoading && !session">
      <button (click)="handleConnect()">Connect Wallet</button>
    </div>
  `,
})
export class AppComponent implements OnInit, OnDestroy {
  session: UserSession | null = null;
  isLoading = true;
  private unsubscribe?: () => void;

  async ngOnInit() {
    // Initialize SDK
    await initialize({
      appId: "your-app-id",
      network: "bitcoinmainnet",
    });

    // Subscribe to state changes
    this.unsubscribe = oviStore.subscribe((state) => {
      this.session = state.session;
      this.isLoading = state.isLoading;
    });

    // Get initial state
    const state = oviStore.getState();
    this.session = state.session;
    this.isLoading = state.isLoading;
  }

  ngOnDestroy() {
    this.unsubscribe?.();
  }

  async handleConnect() {
    const result = await authenticate();
    if (result.status === "success") {
      console.log("Connected!");
    }
  }

  handleDisconnect() {
    clearSession();
  }
}

Configuration Options

Initialize Options

await initialize({
  appId: string,          // Required: Your Oviato App ID
  network?: string,       // Optional: Default network (default: 'bitcoinmainnet')
  env?: 'prod' | 'staging' // Optional: Environment (default: 'prod')
});

Supported Networks

bitcoinmainnet - Bitcoin Mainnet
bitcointestnet - Bitcoin Testnet
ethmainnet - Ethereum Mainnet (soon)
ethsepolia - Ethereum Sepolia Testnet (soon)

Environment Variables

Store your App ID in environment variables:

Vite

# .env.local
VITE_OVIATO_APP_ID=your-app-id-here

await initialize({
  appId: import.meta.env.VITE_OVIATO_APP_ID,
});

Webpack / Create React App

# .env.local
REACT_APP_OVIATO_APP_ID=your-app-id-here

await initialize({
  appId: process.env.REACT_APP_OVIATO_APP_ID,
});

Next.js

# .env.local
NEXT_PUBLIC_OVIATO_APP_ID=your-app-id-here

await initialize({
  appId: process.env.NEXT_PUBLIC_OVIATO_APP_ID,
});

State Management

@oviato/sdk uses Zustand for state management. Subscribe to state changes:

import { oviStore } from "@oviato/sdk";

// Subscribe to all state changes
const unsubscribe = oviStore.subscribe((state) => {
  console.log("Session:", state.session);
  console.log("Ready:", state.ready);
  console.log("Loading:", state.isLoading);
  console.log("Config:", state.config);
});

// Unsubscribe when done
unsubscribe();

// Get current state without subscribing
const currentState = oviStore.getState();

TypeScript Support

@oviato/sdk includes full TypeScript definitions:

import type {
  UserSession,
  OviatoConfig,
  BridgeResponse,
  LoginOptions,
  RegisterOptions,
  AuthenticateOptions,
  ConnectStore,
} from "@oviato/sdk";

const session: UserSession | null = getSession();

Verify Installation

Create a simple test to verify everything is working:

import { initialize, getConfig, isInitialized } from "@oviato/sdk";

// Initialize
await initialize({
  appId: "your-app-id",
  network: "bitcoinmainnet",
});

// Verify initialization
console.log("Initialized:", isInitialized()); // true

// Get config
const config = getConfig();
console.log("Config:", config);