SDK overview

​

Contract status

​

Source documents

• platform.sec-admn.com-2/AGENTS.md
• platform.sec-admn.com-2/sdk/README.md
• platform.sec-admn.com-2/docs/platform-app-package-format.md
• platform.sec-admn.com-2/docs/v1-audit/03b-module-manifest-system.md

​

Start here

1. Scaffold the module with create-aiconnected-module.
2. Fill out platform-app.json.
3. Reuse shared models from @aiconnected/schemas.
4. Expose authenticated function endpoints for declared outputs.
5. Emit platform events and report usage.
6. Validate the manifest and package structure.
7. Import the package through the platform app import APIs.
8. Verify install, capability wiring, and any required dependencies.

• Manifest contracts
• Schemas
• Client and CLI
• Platform app APIs
• Capabilities APIs

​

Golden path

​

1. Scaffold the module

npx create-aiconnected-module

​

2. Fill out the manifest

{
  "schemaVersion": 1,
  "app": {
    "key": "voice-ai",
    "name": "Voice AI",
    "version": "1.0.0",
    "category": "customer-facing",
    "description": "Adds real-time voice to the platform."
  },
  "inputs": [
    {
      "key": "knowledge-base.search",
      "kind": "capability",
      "required": true,
      "title": "Knowledge base search"
    }
  ],
  "outputs": [
    {
      "key": "voice.transcript",
      "kind": "data",
      "title": "Voice transcript"
    }
  ],
  "extends": []
}

​

3. Reuse shared models

import type { Contact, Call, UsageRecord } from "@aiconnected/schemas";

​

4. Use the platform client

import { createPlatformClientFromEnv } from "@aiconnected/client";

const platform = createPlatformClientFromEnv();

await platform.emit("call.started", { call_id: "call_123", contact_id: "contact_456" });
await platform.usage("calls_initiated", 1, "calls");

​

5. Import into the platform

​

Two SDK layers

​

Layer 1: Connection layer

• packages/app-sdk

• Normalize module manifests
• Validate manifest correctness
• Assess compatibility against the app catalog
• Generate connection suggestions
• Normalize imported UI and color usage during app import

• normalizeAppManifest()
• validateAppManifest()
• assessAppManifest()

​

Layer 2: Services layer

• sdk/packages/client
• sdk/packages/manifest
• sdk/packages/schemas
• sdk/packages/ui
• sdk/packages/cli

• Shared data models
• Manifest schema and validation
• Platform event, function-call, and usage-reporting client
• Shared UI components
• Module scaffolding

​

Hard rules from the v1 SDK docs

• App keys are kebab-case.
• Modules ship a manifest file.
• Shared models come from @aiconnected/schemas.
• Shared UI imports come from @aiconnected/ui.
• Modules do not connect directly to one another.
• Cross-module calls go through platform registry or event-bus contracts.

​

Compatibility matrix

​

v1 reality vs v2 target

​

Implemented in v1

• manifest normalization and validation
• registry-mediated client calls
• platform app import
• capability import and install flows
• shared schema package

​

Carry forward to v2

• manifest-first module registration
• shared schema ownership
• event and usage reporting
• admin import and assessment workflow

​

Known migration risks

• two overlapping manifest shapes exist in v1
• app key naming is stricter than some older comments and examples
• UI component models differ slightly between importer and validator packages

​

Common failure points

• module uses snake_case app IDs instead of kebab-case
• manifest declares required inputs with no provider in the catalog
• module emits events but never exposes declared outputs
• module redefines shared models instead of importing them
• importer accepts the package but returns warnings the team ignores

​

What to improve next