SDK Guides

IntentEmoji provides official SDKs for JavaScript/TypeScript and Python. Both packages wrap the API with type safety, automatic retry, local caching, and offline fallback. A React component is included in the JavaScript package.

JavaScript / TypeScript

Installation

npm install intentemoji

Or with yarn:

yarn add intentemoji

Initialization

import { IntentEmoji } from 'intentemoji';

const ie = new IntentEmoji({
  apiKey: process.env.INTENTEMOJI_API_KEY,
  // Optional configuration
  defaultProfile: 'professional',
  cache: true,           // Enable local cache (default: true)
  cacheTTL: 3600,        // Cache TTL in seconds (default: 3600)
  retries: 3,            // Max retry attempts (default: 3)
  timeout: 5000,         // Request timeout in ms (default: 5000)
});

enhance()

Enhance plain text with intentional emoji placement.

const result = await ie.enhance(
  'We shipped the new billing system. Invoices generate in under 2 seconds.',
  {
    profile: 'professional',
    density: 'moderate',
    preserveExisting: true,
  }
);

console.log(result.text);
// "🚀 We shipped the new billing system.\n\n⚡ Invoices generate in under 2 seconds."

console.log(result.emojiCount);     // 2
console.log(result.preloadRatio);   // 1.0
console.log(result.positions);      // Array of position objects

analyze()

Analyze existing text for emoji placement quality.

const analysis = await ie.analyze(
  'Just deployed 🚀 All tests passing 👍',
  { targetProfile: 'technical' }
);

console.log(analysis.score);           // 42
console.log(analysis.preloadRatio);    // 0.0
console.log(analysis.suggestions);     // Array of suggestion strings
console.log(analysis.density);         // "high"

reposition()

Move existing emoji to better positions without adding or removing.

const result = await ie.reposition(
  'Server crashed at 3am 💥 Root cause was a memory leak 🐛',
  { profile: 'professional' }
);

console.log(result.text);
// "💥 Server crashed at 3am. 🐛 Root cause was a memory leak."

console.log(result.emojiMoved);     // 2
console.log(result.emojiRemoved);   // 0

suggest()

Get emoji suggestions for a piece of text.

const suggestions = await ie.suggest(
  'Deployment complete. All tests passing.',
  { profile: 'technical', limit: 3 }
);

suggestions.forEach(s => {
  console.log(`${s.emoji} (${s.position}) - ${s.confidence}`);
});
// ✅ (preload) - 0.94
// 🚀 (preload) - 0.87
// 🟢 (preload) - 0.82

Offline Fallback

When the API is unreachable, the SDK falls back to a local rule-based engine. The fallback uses a simplified version of the placement algorithm that runs entirely in-process. It does not require network access.

const ie = new IntentEmoji({
  apiKey: process.env.INTENTEMOJI_API_KEY,
  offlineFallback: true,   // Enable offline mode (default: true)
});

// If the API is down, this still returns a result
// using the local rule-based engine
const result = await ie.enhance('Server is back online.', {
  profile: 'technical',
});

console.log(result.offline);  // true if fallback was used

TypeScript Types

Full type definitions are included. Key types:

import type {
  IntentEmojiConfig,
  EnhanceOptions,
  EnhanceResult,
  AnalyzeResult,
  RepositionResult,
  Suggestion,
  EmojiPosition,
  Profile,
  Density,
} from 'intentemoji';

Python

Installation

pip install intentemoji

Initialization

import os
from intentemoji import IntentEmoji

ie = IntentEmoji(
    api_key=os.environ["INTENTEMOJI_API_KEY"],
    default_profile="professional",
    cache=True,
    cache_ttl=3600,
    retries=3,
    timeout=5.0,
)

enhance()

result = ie.enhance(
    "We shipped the new billing system. Invoices generate in under 2 seconds.",
    profile="professional",
    density="moderate",
)

print(result.text)
# "🚀 We shipped the new billing system.\n\n⚡ Invoices generate in under 2 seconds."

print(result.emoji_count)      # 2
print(result.preload_ratio)    # 1.0

analyze()

analysis = ie.analyze(
    "Just deployed 🚀 All tests passing 👍",
    target_profile="technical",
)

print(analysis.score)           # 42
print(analysis.preload_ratio)   # 0.0
print(analysis.suggestions)     # List of suggestion strings

reposition()

result = ie.reposition(
    "Server crashed at 3am 💥 Root cause was a memory leak 🐛",
    profile="professional",
)

print(result.text)
print(result.emoji_moved)       # 2

suggest()

suggestions = ie.suggest(
    "Deployment complete. All tests passing.",
    profile="technical",
    limit=3,
)

for s in suggestions:
    print(f"{s.emoji} ({s.position}) - {s.confidence}")

Async Support

The Python SDK includes an async client for use with asyncio.

from intentemoji import AsyncIntentEmoji

ie = AsyncIntentEmoji(api_key=os.environ["INTENTEMOJI_API_KEY"])

async def main():
    result = await ie.enhance(
        "Async support is here.",
        profile="technical",
    )
    print(result.text)

React Component

The JavaScript SDK includes a React component for rendering enhanced text with real-time enhancement as users type.

IntentEmojiProvider

Wrap your app with the provider to configure the client once.

import { IntentEmojiProvider } from 'intentemoji/react';

function App() {
  return (
    <IntentEmojiProvider apiKey={process.env.NEXT_PUBLIC_INTENTEMOJI_API_KEY}>
      <MyComponent />
    </IntentEmojiProvider>
  );
}

useIntentEmoji Hook

Access the client and enhancement functions from any component.

import { useIntentEmoji } from 'intentemoji/react';

function StatusUpdate() {
  const { enhance, isLoading } = useIntentEmoji();
  const [text, setText] = useState('');
  const [enhanced, setEnhanced] = useState('');

  const handleEnhance = async () => {
    const result = await enhance(text, { profile: 'professional' });
    setEnhanced(result.text);
  };

  return (
    <div>
      <textarea value={text} onChange={e => setText(e.target.value)} />
      <button onClick={handleEnhance} disabled={isLoading}>
        {isLoading ? 'Enhancing...' : 'Enhance'}
      </button>
      {enhanced && <p>{enhanced}</p>}
    </div>
  );
}

EnhancedText Component

A display component that renders text with enhanced emoji. Handles the API call and displays a loading state.

import { EnhancedText } from 'intentemoji/react';

function Notification({ message }) {
  return (
    <EnhancedText
      text={message}
      profile="professional"
      density="low"
      fallback={message}
    />
  );
}

Error Handling

Both SDKs throw typed errors that map to the API error codes.

JavaScript

import { IntentEmojiError } from 'intentemoji';

try {
  const result = await ie.enhance(text);
} catch (err) {
  if (err instanceof IntentEmojiError) {
    console.error(err.code);     // "rate_limit_exceeded"
    console.error(err.status);   // 429
    console.error(err.message);  // Human-readable message
  }
}

Python

from intentemoji.exceptions import IntentEmojiError, RateLimitError

try:
    result = ie.enhance(text)
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds.")
except IntentEmojiError as e:
    print(f"Error {e.status}: {e.code} - {e.message}")