npm package: @inceptionai/georacle-sdk
Description: GeOracle SDK for integrating custom websites with GeOracle AI platform - Pull-based GEO analysis API
Author: GeOracle
Latest version: 0.2.0

# @inceptionai/georacle-sdk

Official SDK for integrating your website with [GeOracle](https://georacle.ai) - AI-powered Generative Engine Optimization (GEO) platform.

> **GeOracle** bridges the gap as the internet shifts from human readers to AI readers. We help your website become perfectly discoverable by AI systems like ChatGPT, Claude, and Perplexity through GEO (Generative Engine Optimization).

---

## What's New in v0.2.0

### Pull-Based GEO Analysis API

New in v0.2.0: **Analyze any page's GEO readiness** without manual content sync.

```bash
npm install @inceptionai/georacle-sdk
```

```typescript
import { fetchGeoContext } from '@inceptionai/georacle-sdk/server';

// Analyze a page's GEO readiness
const geoContext = await fetchGeoContext({
  pageContext: {
    locale: 'en-CA',
    regionCode: 'CA',
    categoryPath: '/health-fitness/vitamins',
    categoryTitle: 'Best Women\'s Multivitamins',
    productCount: 7,
    products: [
      { title: 'Vitamin D3', price: { listingPrice: 24.99, currency: 'CAD' } },
      // ... more products
    ],
  },
  requestedMetrics: ['shipping-coverage', 'price-localization', 'tax-calculation'],
});

// Returns:
// {
//   geoReadinessScores: {
//     shippingCoverage: { score: 82, status: 'good', ... },
//     priceLocalization: { score: 100, status: 'excellent', ... },
//     taxCalculation: { score: 78, status: 'good', ... },
//     ...
//   },
//   overallGeoReadiness: { score: 87, grade: 'A', status: 'excellent' },
//   productEnrichments: [ ... ], // Per-product GEO data
//   recommendations: [ ... ], // Actionable improvements
// }
```

---

## Features

### Two Integration Modes

#### Mode 1: Content Sync (Legacy)
Sync static/semi-static content to GeOracle for GEO analysis.

```typescript
import { GeOracleClient } from '@inceptionai/georacle-sdk';

const client = new GeOracleClient({
  apiKey: process.env.GEORACLE_API_KEY,
  teamId: process.env.GEORACLE_TEAM_ID,
});

await client.sync({
  id: 'article-1',
  type: 'Article',
  title: 'My Article',
  content: '...',
  url: 'https://example.com/article-1',
});
```

#### Mode 2: Page Analysis (New)
Analyze any page's GEO readiness with product-level enrichments.

```typescript
import { fetchGeoContext } from '@inceptionai/georacle-sdk/server';
import { GeoProvider, useProductEnrichment } from '@inceptionai/georacle-sdk/react';

export default async function Page() {
  const geoContext = await fetchGeoContext({
    pageContext: { ... },
    requestedMetrics: [ ... ],
  });

  return (
    <GeoProvider data={geoContext}>
      <ProductList />
    </GeoProvider>
  );
}

function ProductList() {
  return (
    <div>
      {products.map((product, i) => (
        <ProductCard key={i} product={product} index={i} />
      ))}
    </div>
  );
}

function ProductCard({ product, index }) {
  const geoData = useProductEnrichment(index);
  
  return (
    <div>
      <h2>{product.title}</h2>
      {geoData?.shipping.availableToRegion && (
        <span>Ships in {geoData.shipping.estimatedDays?.min}-{geoData.shipping.estimatedDays?.max} days</span>
      )}
      {geoData?.pricing.taxInfo && (
        <span>+${geoData.pricing.taxInfo.totalTax?.estimated} tax</span>
      )}
    </div>
  );
}
```

### GEO Readiness Metrics

The SDK analyzes 6 key GEO metrics:

1. **Shipping Coverage** - Availability to your target region
2. **Price Localization** - Regional currency and pricing
3. **Stock Availability** - Real-time inventory status
4. **Tax Calculation** - Regional and federal tax rates
5. **Delivery Estimates** - Carrier-specific delivery dates
6. **Regional Promotions** - Location-specific offers

Each metric returns:
- `score` (0-100)
- `status` ('excellent' | 'good' | 'fair' | 'poor')
- `details` (explanation)
- `recommendations` (actionable improvements)

### Framework Support

| Framework | Mode | Status |
|-----------|------|--------|
| **Next.js** | Both | ✅ Full support |
| **React** | Page Analysis | ✅ Hooks + Provider |
| **Vue 3** | Page Analysis | ✅ Composables |
| **Vanilla JS** | Page Analysis | ✅ Direct API access |

---

## Installation

```bash
npm install @inceptionai/georacle-sdk
# or
pnpm add @inceptionai/georacle-sdk
# or
yarn add @inceptionai/georacle-sdk
```

---

## Quick Start

### 1. Get Your API Key

1. Go to [GeOracle Dashboard](https://georacle.ai/dashboard)
2. Navigate to Settings → Integrations
3. Generate an API key (starts with `geo_sk_`)

### 2. Set Environment Variables

```bash
# .env.local
GEORACLE_API_KEY=geo_sk_your_key_here
GEORACLE_TEAM_ID=your_team_id
```

### 3. Analyze a Page (Next.js Example)

```typescript
// app/[...slug]/page.tsx
import { fetchGeoContext } from '@inceptionai/georacle-sdk/server';
import { GeoProvider, useGeoScores } from '@inceptionai/georacle-sdk/react';

export default async function Page({ params }) {
  const products = await getProducts(params.slug);
  
  const geoContext = await fetchGeoContext({
    pageContext: {
      locale: 'en-CA',
      regionCode: 'CA',
      categoryPath: params.slug,
      categoryTitle: 'Product Category',
      productCount: products.length,
      products: products.map(p => ({
        title: p.title,
        price: { listingPrice: p.price, currency: 'CAD' },
      })),
    },
    requestedMetrics: [
      'shipping-coverage',
      'price-localization',
      'stock-availability',
      'tax-calculation',
    ],
  });

  return (
    <GeoProvider data={geoContext}>
      <main>
        <ProductGrid products={products} />
      </main>
    </GeoProvider>
  );
}
```

### 4. Use Data in Components

```typescript
// components/ProductCard.tsx
'use client';

import { useProductEnrichment, useGeoScores } from '@inceptionai/georacle-sdk/react';

export function ProductCard({ product, index }) {
  const geoData = useProductEnrichment(index);
  const scores = useGeoScores();

  return (
    <div className="product-card">
      <h3>{product.title}</h3>
      <p>${product.price}</p>

      {/* Show shipping info if available */}
      {geoData?.shipping.availableToRegion && (
        <div className="text-green-600">
          ✓ Ships in {geoData.shipping.estimatedDays?.min}-{geoData.shipping.estimatedDays?.max} days
        </div>
      )}

      {/* Show tax estimate */}
      {geoData?.pricing.taxInfo?.totalTax && (
        <small>+${geoData.pricing.taxInfo.totalTax.estimated.toFixed(2)} tax</small>
      )}

      {/* Show compliance badges */}
      {geoData?.compliance.certifications?.map(cert => (
        <span key={cert} className="badge">{cert}</span>
      ))}
    </div>
  );
}
```

---

## API Reference

### `fetchGeoContext(request, options)`

Fetch GEO analysis for a page.

**Parameters:**
- `request.pageContext` - Page metadata and products
- `request.requestedMetrics` - Array of metrics to analyze
- `options.cache` - Cache duration in seconds (default: 3600)
- `options.apiKey` - API key (defaults to env var)

**Returns:**
```typescript
{
  pageId: string;
  analyzedAt: string;
  geoReadinessScores: {
    shippingCoverage: GeoScore;
    priceLocalization: GeoScore;
    stockAvailability: GeoScore;
    taxCalculation: GeoScore;
    deliveryEstimates: GeoScore;
    regionalPromotions: GeoScore;
  };
  overallGeoReadiness: {
    score: number;    // 0-100
    grade: string;    // 'A+', 'A', 'B', 'C', 'D', 'F'
    status: string;   // 'excellent', 'needs-improvement', etc.
  };
  productEnrichments: ProductEnrichment[];
  recommendations: Recommendation[];
}
```

### React Hooks

#### `GeoProvider`
Wrap your component tree to provide GEO context.

```tsx
<GeoProvider data={geoContext}>
  <App />
</GeoProvider>
```

#### `useGeoContext()`
Access the full GEO analysis response.

```tsx
const geoData = useGeoContext();
console.log(geoData?.overallGeoReadiness.score);
```

#### `useGeoScores()`
Get all readiness metrics.

```tsx
const scores = useGeoScores();
return <div>{scores?.shippingCoverage.score}%</div>;
```

#### `useProductEnrichment(index)`
Get GEO data for a specific product.

```tsx
const geoData = useProductEnrichment(0);
return <div>{geoData?.shipping.availableToRegion ? 'In Stock' : 'Out of Stock'}</div>;
```

#### `useOverallScore()`
Get the page's overall GEO score.

```tsx
const overall = useOverallScore();
return <div>Grade: {overall?.grade}</div>;
```

#### `useRecommendations()`
Get actionable improvement recommendations.

```tsx
const recommendations = useRecommendations();
return (
  <ul>
    {recommendations.map(r => <li key={r.message}>{r.message}</li>)}
  </ul>
);
```

### Vue 3 Composables

```typescript
import { provideGeoContext, useGeoContext, useProductEnrichment } from '@inceptionai/georacle-sdk/vue';

export default {
  setup() {
    const geoContext = await fetchGeoContext({...});
    provideGeoContext(geoContext);

    const productGeo = useProductEnrichment(0);
    return { productGeo };
  },
};
```

### Schema Utilities

Generate Schema.org JSON-LD for AI discoverability.

```typescript
import {
  generateArticleSchema,
  generateProductSchema,
  generateFAQSchema,
  injectJsonLd,
} from '@inceptionai/georacle-sdk/schemas';

const schema = generateArticleSchema({
  title: 'My Article',
  description: 'Description',
  publishedAt: '2024-01-15',
  url: 'https://example.com/article',
});

injectJsonLd(schema, 'article-schema');
```

---

## Error Handling

The SDK gracefully degrades if the GeOracle API is unavailable.

```typescript
const geoContext = await fetchGeoContext({...});

if (!geoContext) {
  console.log('GeOracle API unavailable - site still works');
  // Render without GEO data
}
```

---

## Pricing

| Plan | Price | API Calls/Day |
|------|-------|---------------|
| Free | $0 | 1,000 |
| Pro | $49/mo | 100,000 |
| Enterprise | Custom | Unlimited |

Each call analyzes a page and up to 100 products.

---

## Support

- 📚 [Documentation](https://georacle.ai/docs/sdk)
- 💬 [Discord Community](https://discord.gg/georacle)
- 📧 [Email Support](mailto:support@georacle.ai)
- 🐛 [Report Issues](https://github.com/inceptionai/georacle-sdk/issues)

---

## License

MIT © GeOracle

---

**Made with ❤️ by the GeOracle team**