@circle-apps/sdk
Version:
Official SDK for Celia Mini Apps integration
281 lines (220 loc) • 7.15 kB
Markdown
<div align="center">
<h1>@circle-apps/sdk</h1>
<p>Official TypeScript/JavaScript SDK for Celia Mini Apps</p>
[](https://www.npmjs.com/package/@circle-apps/sdk)
[](https://opensource.org/licenses/MIT)
[](http://www.typescriptlang.org/)
</div>
## ✨ 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
```bash
# 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
```tsx
// 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
```tsx
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
```typescript
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
```typescript
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
```typescript
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
```typescript
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**.
```typescript
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:
```bash
npm install
```
3. Build the project:
```bash
npm run build
```
4. Run tests:
```bash
npm test
```
## 🤝 Contributing
Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) to get started.
## 📄 License
MIT © [Celia Team](https://github.com/celia-team)
---
<div align="center">
Made with ❤️ by the Celia Team
</div>