Getting Started

Go from zero to a published package in under an hour.

Overview

The Aiffinity Provider Platform lets you ship functionality packages that give Aiven and Space new capabilities. Providers publish data, actions, state, event contracts, and surface guidance. Aiffinity owns all consumer UI rendering.

The onboarding flow takes you through seven steps: account creation, email verification, app registration, package creation, conformance testing, submission, and publication.

Prerequisites

• A verified email address
• Node.js 20+ (for the SDK and CLI tools)
• A basic understanding of REST APIs and JSON
• Your service's OAuth or API key credentials (if applicable)

Onboarding Steps

curl -X POST https://api.aiffinity.me/v1/providers/account \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Acme Weather Inc.",
    "email": "[email protected]",
    "password": "your-secure-password"
  }'

curl -X POST https://api.aiffinity.me/v1/providers/account/verify \
  -H "Content-Type: application/json" \
  -d '{ "token": "abc123-verification-token" }'

# Using the SDK
import { ProviderPlatformClient } from '@aiffinity/provider-platform-sdk';

const client = new ProviderPlatformClient({
  clientId: process.env.AIFFINITY_CLIENT_ID,
  clientSecret: process.env.AIFFINITY_CLIENT_SECRET,
});

const app = await client.apps.create({
  name: 'Acme Weather',
  description: 'Real-time weather data and forecasts',
  redirectUris: ['https://acmeweather.com/callback'],
  webhookUrl: 'https://acmeweather.com/webhooks/aiffinity',
});

# Using curl
curl -X POST https://api.aiffinity.me/v1/providers/apps \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Weather",
    "description": "Real-time weather data and forecasts",
    "redirect_uris": ["https://acmeweather.com/callback"],
    "webhook_url": "https://acmeweather.com/webhooks/aiffinity"
  }'

const pkg = await client.packages.create({
  appId: app.id,
  name: 'Weather Widgets',
  slug: 'acme-weather-widgets',
  description: 'Live weather conditions and forecasts for any location',
  riskTier: 'data_only',
  capabilities: [
    {
      type: 'state',
      schema: {
        location: { type: 'string', required: true },
        temperature: { type: 'number' },
        condition: { type: 'string' },
        forecast: { type: 'array', items: { type: 'object' } },
      },
    },
  ],
});

const result = await client.packages.validate(pkg.id, pkg.latestVersionId);

console.log(result.score);        // 92
console.log(result.passed);       // true
console.log(result.dimensions);   // { schema: 18, contracts: 16, ... }

# CLI alternative
npx @aiffinity/provider-platform-sdk validate \
  --package-id $PACKAGE_ID \
  --version-id $VERSION_ID

await client.packages.submit(pkg.id, pkg.latestVersionId);

curl -X POST "https://api.aiffinity.me/v1/providers/packages/manage/$PKG_ID/versions/$VER_ID/submit" \
  -H "Authorization: Bearer $TOKEN"

await client.packages.publish(pkg.id, pkg.latestVersionId);

Walkthrough: Build a Weather Widget

Let's build a complete weather widget package from scratch. This example uses the state capability to provide real-time weather data that Aiffinity renders as a widget on the user's Aiffinity screen.

1. Project setup

mkdir acme-weather-provider && cd acme-weather-provider
npm init -y
npm install @aiffinity/provider-platform-sdk

2. Define the capability descriptor

// capability.json
{
  "type": "state",
  "name": "current_weather",
  "description": "Current weather conditions for a user's location",
  "refreshInterval": 900,
  "schema": {
    "type": "object",
    "properties": {
      "location": { "type": "string", "description": "City or coordinates" },
      "temperature_c": { "type": "number" },
      "condition": { "type": "string", "enum": ["sunny", "cloudy", "rainy", "snowy", "windy", "stormy"] },
      "humidity_pct": { "type": "number", "minimum": 0, "maximum": 100 },
      "wind_speed_kmh": { "type": "number" },
      "forecast_3day": {
        "type": "array",
        "maxItems": 3,
        "items": {
          "type": "object",
          "properties": {
            "day": { "type": "string" },
            "high_c": { "type": "number" },
            "low_c": { "type": "number" },
            "condition": { "type": "string" }
          }
        }
      }
    },
    "required": ["location", "temperature_c", "condition"]
  },
  "surfaceGuidance": {
    "intent": "ambient_context",
    "placement": ["home_widgets", "daily_brief"],
    "components": ["stat_row", "sparkline"]
  }
}

3. Implement the runtime handler

// handler.ts
import { ProviderPlatformClient, CapabilityHandler } from '@aiffinity/provider-platform-sdk';

const client = new ProviderPlatformClient({
  clientId: process.env.AIFFINITY_CLIENT_ID!,
  clientSecret: process.env.AIFFINITY_CLIENT_SECRET!,
});

const weatherHandler: CapabilityHandler = {
  async execute(request) {
    const { location } = request.params;

    // Fetch from your weather API
    const weather = await fetchWeatherData(location);

    return {
      status: 'ok',
      data: {
        location: weather.city,
        temperature_c: weather.temp,
        condition: weather.condition,
        humidity_pct: weather.humidity,
        wind_speed_kmh: weather.windSpeed,
        forecast_3day: weather.forecast.slice(0, 3).map(day => ({
          day: day.name,
          high_c: day.high,
          low_c: day.low,
          condition: day.condition,
        })),
      },
      ttl: 900,
    };
  },
};

client.runtime.registerHandler('current_weather', weatherHandler);
client.runtime.start({ port: 3000 });

4. Validate and submit

# Run conformance suite locally
npx @aiffinity/provider-platform-sdk validate --local ./capability.json

# Create the package via API
npx @aiffinity/provider-platform-sdk create-package \
  --app-id $APP_ID \
  --name "Acme Weather" \
  --descriptor ./capability.json \
  --risk-tier data_only

# Submit for review
npx @aiffinity/provider-platform-sdk submit \
  --package-id $PACKAGE_ID \
  --version-id $VERSION_ID

5. Monitor in the console

Track your package status, install counts, and error rates at dev.aiffinity.me. The dashboard shows real-time metrics, webhook delivery logs, and conformance history.

Next Steps

• Runtime Configuration — Set up auth profiles, webhooks, and capability templates
• Capabilities Reference — Deep dive into the five capability modes
• SDK Documentation — Full client API and CLI reference
• Testing & Sandbox — Run conformance tests and use the sandbox environment
• Widget Components — Browse the component catalog for surface guidance