✨ Features

• 🔒 Authentication - Seamless authentication with Celia
• 📱 WebView Integration - Built for React Native WebView
• 📦 TypeScript Support - Full type definitions included
• 🔄 Promise-based API - Modern async/await patterns
• 🎯 React Hooks - Easy integration with React components
• 🌐 Language Support - Automatic language detection
• 🔗 Share Functionality - Easy content sharing

🚀 Installation

# Using npm
npm install @circle-apps/sdk

# Using yarn
yarn add @circle-apps/sdk

# Using pnpm
pnpm add @circle-apps/sdk

📖 Quick Start

1. Wrap your app with CeliaSDKProvider

// App.tsx
import { CeliaSDKProvider } from '@circle-apps/sdk';

function App() {
  return (
    <CeliaSDKProvider
      fallback={
        <div style={{ textAlign: 'center', padding: 20 }}>
          <h2>Please open in Celia App</h2>
          <p>This mini-app requires the Celia app to function properly.</p>
        </div>
      }
      enableOutsideWebView={false} // Set to true to allow SDK to work outside of Celia WebView (for development)
    >
      <YourApp />
    </CeliaSDKProvider>
  );

2. Use the SDK in your components

import { useCeliaSDK } from "@circle-apps/sdk";
import { useState } from "react";

function AuthComponent() {
  const { sdk, isLoading, isReady, isWebView, error, language } = useCeliaSDK();
  const [user, setUser] = useState(null);

  // Handle loading state
  if (isLoading) {
    return <div>Initializing Celia SDK...</div>;
  }

  // Handle errors
  if (error) {
    return <div>Error: {error.message}</div>;
  }

  // Handle WebView check
  if (!isWebView) {
    return <div>Please open this app in Celia</div>;
  }

  // Handle authentication
  const handleLogin = async () => {
    try {
      const result = await sdk.authenticate({
        appID: "your-app-id",
      });
      console.log("Authentication successful", result);
      setUser(result);
    } catch (err) {
      console.error("Authentication failed", err);
    }
  };

  return (
    <div>
      <p>Current language: {language || "en"}</p>
      {user ? (
        <div>Welcome back! Auth code: {user.code}</div>
      ) : (
        <button onClick={handleLogin}>Login with Celia</button>
      )}
    </div>
  );
}

🎛️ Core Features

Authentication

const { sdk } = useCeliaSDK();

// Start authentication
const result = await sdk.authenticate({
  appID: "your-app-id", // Required
});

// Authentication response contains:
// {
//   code: string;       // Authentication code
//   expiresIn?: number; // Optional expiration time in seconds
// }

Showing Ads

const { sdk } = useCeliaSDK();

// Show a rewarded ad
const showAd = async () => {
  try {
    const result = await sdk.showAd({
      type: "rewarded",
      adUnitId: "your-ad-unit-id",
      testMode: true, // Optional, for testing
    });
    console.log("Ad result:", result);
    // Result contains:
    // {
    //   type: string;        // Ad type
    //   adUnitId: string;    // Ad unit ID
    //   revenue?: number;    // Optional revenue information
    //   currency?: string;   // Optional currency code
    //   completed: boolean;  // Whether the ad was completed
    // }
  } catch (error) {
    console.error("Ad failed:", error);
  }
};

Sharing Content

const { sdk } = useCeliaSDK();

// Share content
const shareContent = async () => {
  try {
    await sdk.share({
      title: "Check out this app!",
      message: "I found this amazing app on Celia",
      url: "https://example.com",
      dialogTitle: "Share via",
    });
    console.log("Content shared successfully");
  } catch (error) {
    console.error("Share failed:", error);
  }
};

Getting Device Language

const { sdk, language } = useCeliaSDK();

// Language is automatically fetched during initialization
console.log("Current language:", language); // e.g., 'en', 'es', 'fr'

// You can also fetch it manually
const fetchLanguage = async () => {
  try {
    const result = await sdk.getLanguage();
    console.log("Device language:", result.language);
  } catch (error) {
    console.error("Failed to get language:", error);
  }
};

🔌 API Reference

CeliaSDKProvider

Props

• children: ReactNode to render when SDK is initialized
• fallback: ReactNode to render when not in Celia WebView
• enableOutsideWebView: (Optional) Allow SDK to work outside of Celia WebView (default: false)

useCeliaSDK()

Hook to access the SDK instance. Only available within CeliaSDKProvider.

const {
  sdk, // The SDK instance (null until initialized)
  isWebView, // boolean: true if running in Celia WebView
  isLoading, // boolean: true during initialization
  isReady, // boolean: true when SDK is fully initialized
  error, // Error object if initialization failed
  language, // string: current device language (e.g., 'en')
} = useCeliaSDK();

Available Methods

sdk.authenticate(options: AuthOptions): Promise<AuthResponse>

• options.appID: (Required) Your app's registered application ID
• Returns: Promise that resolves with auth data containing code and optional expiresIn

sdk.showAd(options: AdOptions): Promise<AdResponse>

• options.type: 'interstitial' | 'rewarded'
• options.adUnitId: Your ad unit ID
• options.testMode: (Optional) Enable test mode for development
• Returns: Promise that resolves with ad result data

sdk.share(options: ShareOptions): Promise<void>

• options.title: (Optional) Share title
• options.message: (Optional) Share message
• options.url: (Optional) URL to share
• options.dialogTitle: (Optional) Title for the share dialog
• Returns: Promise that resolves when sharing is complete

sdk.getLanguage(): Promise<LanguageResponse>

• Returns: Promise that resolves with the device language (e.g., { language: 'en' })

SDK Properties

• sdk.isInitialized: boolean - Whether the SDK has been initialized
• sdk.isWebView: boolean - Whether the app is running in a WebView
• sdk.isCircleMiniApp: boolean - Whether the app is a Circle Mini App

🔧 Development

1. Clone the repository
2. Install dependencies:

   npm install

3. Build the project:

   npm run build

4. Run tests:

   npm test

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide to get started.

📄 License

MIT © Celia Team