Sociogram Mini Apps SDK

A TypeScript SDK for creating mini apps that integrate with Sociogram.

Installation

npm install @sociogram-dev/mini-apps-sdk
# or
yarn add @sociogram-dev/mini-apps-sdk
# or
pnpm add @sociogram-dev/mini-apps-sdk

TypeScript Support

This SDK is written in TypeScript and provides full type definitions. You can use it in your TypeScript projects with full type safety and autocompletion.

Usage

Basic Setup

import { Sociogram } from '@sociogram-dev/mini-apps-sdk';

// The SDK is automatically initialized and available globally
const miniApp = Sociogram.MiniApp;

// Access initial data
console.log(miniApp.initData);

// Get SDK version
console.log(miniApp.version);

User Interactions

// Get user's followers
const followersRequestId = miniApp.getFollowers(
  { limit: 10, cursor: 'next_page_cursor' },
  (response) => {
    if (response.error) {
      console.error(response.error);
      return;
    }
    console.log('Followers:', response.rows);
    console.log('Next cursor:', response.cursor);
  }
);

// Get users that a user is following
const followingRequestId = miniApp.getFollowing(
  { limit: 10 },
  (response) => {
    if (response.error) {
      console.error(response.error);
      return;
    }
    console.log('Following:', response.rows);
  }
);

// Get user's friends
const friendsRequestId = miniApp.getFriends(
  { limit: 10 },
  (response) => {
    if (response.error) {
      console.error(response.error);
      return;
    }
    console.log('Friends:', response.rows);
  }
);

// Follow a user
miniApp.followUser('user_address');

Post Actions

// Like a post
miniApp.openLikeModal({
  postId: 'post_id'
});

// Tip a post
miniApp.openTipModal({
  postId: 'post_id'
});

// Reward a post
miniApp.openRewardModal({
  postId: 'post_id'
});

Navigation and Sharing

// Open a link in the browser
miniApp.openLink('https://example.com', {
  // Optional parameters
  target: '_blank'
});

// Share content
miniApp.share({
  text: 'Check this out!',
  url: 'https://example.com'
});

Clipboard Operations

// Read text from clipboard
miniApp.readTextFromClipboard('text_to_read');

Invoice Handling

// Open an invoice
const invoiceId = miniApp.openInvoice(
  {
    title: 'Purchase Item',
    price: 10,
    currency: 'usd', // or 'sol'
    invoicePayload: {
      // Your custom payload data
      itemId: '123',
      description: 'Premium subscription'
    }
  },
  (status) => {
    if (status === 'success') {
      console.log('Payment successful!');
    } else {
      console.log('Payment failed');
    }
  }
);

WebView Communication

// Access WebView API directly
const webView = Sociogram.WebView;

// Post an event
webView.postEvent('custom_event', { data: 'value' });

// Listen for events
webView.onEvent('custom_event', (eventType, eventData) => {
  console.log(`Received ${eventType}:`, eventData);
});

// Remove event listener
webView.offEvent('custom_event', callback);

// Check if running in iframe
const isIframe = webView.isIframe;

// Access initialization parameters
const initParams = webView.initParams;

Utility Functions

const { urlSafeDecode, urlParseQueryString, safeParseUrlParams } = Sociogram.Utils;

// Decode URL-safe strings
const decoded = urlSafeDecode('encoded_string');

// Parse query string
const params = urlParseQueryString('?key=value');

// Safely parse URL parameters
const safeParams = safeParseUrlParams();

Type Definitions

The SDK provides comprehensive TypeScript type definitions. Here are the main types:

User Interface

interface User {
  _id: string;
  createdAt: string;
  id: string;
  address: string;
  domain: string | null;
  name: string;
  avatar: string;
  verified: boolean;
  subscription: {
    following: number;
    followers: number;
  };
  twitter: {
    twitterId: string | null;
    name: string | null;
    followers: number;
  };
  isFollowed: boolean;
}

API Response Types

interface UsersResponse {
  cursor: string | null;
  rows: User[];
  error?: string;
}

interface PostActionData {
  postId: string;
}

interface InvoiceData {
  invoicePayload: Record<string, unknown>;
  title: string;
  price: number;
  currency: CurrencyType;
}

enum CurrencyType {
  USD = 'usd',
  SOL = 'sol'
}

Event Handling

type EventType = string;
type EventData = unknown;
type EventCallback = (eventType: EventType, eventData: EventData) => void;

// Register event handler
Sociogram.WebView.onEvent('event_type', (type, data) => {
  console.log(`Event ${type}:`, data);
});

// Remove event handler
Sociogram.WebView.offEvent('event_type', callback);

Environment Detection

The SDK automatically detects the environment it's running in:

• iframe: When running inside an iframe
• react-native: When running in a React Native WebView
• web: When running in a regular web browser

const isIframe = Sociogram.WebView.isIframe;

Error Handling

The SDK provides error handling through callbacks and response objects:

// Error handling in user list responses
miniApp.getFollowers({}, (response) => {
  if (response.error) {
    console.error('Error fetching followers:', response.error);
    return;
  }
  // Handle successful response
});

// Error handling in invoice callbacks
miniApp.openInvoice(invoiceData, (status) => {
  if (status === 'failed') {
    console.error('Payment failed');
    return;
  }
  // Handle successful payment
});

Development

Building

# Install dependencies
yarn install

# Build the SDK
yarn build

# Watch mode for development
yarn build:watch

Testing

# Run tests
yarn test

# Watch mode for tests
yarn test:watch

License

MIT