P131 — AIEP — Integration Subscription and SDK Contract

Publication Date: 2026-03-13 Status: Open Source Prior Art Disclosure Licence: Apache License 2.0 Author/Organisation: Phatfella Ltd Schema: AIEP_OS_SPEC_TEMPLATE v1.0.1 — https://aiep.dev/schemas/aiep-os-spec-template/v1.0.1

Framework Context

[0001] This disclosure operates within an Architected Instruction and Evidence Protocol (AIEP) environment as defined in United Kingdom patent application number GB2519711.2, filed 20 November 2025, and GB2519798.9, filed 20 November 2025, the entire contents of which are incorporated herein by reference.

[0002] The present disclosure specifies two components of an AIEP SaaS integration layer: (a) an Integration Registry that manages outbound event subscriptions to external channels including Slack, Microsoft Teams, webhooks, and email, each entry carrying a cryptographic configuration hash and a Cloudflare Secrets reference for its signing key; and (b) a PieaClient TypeScript SDK that external developers use to query an AIEP SaaS product programmatically, add sources to the learning list, and perform health checks.

Field of the Disclosure

[0003] This disclosure relates to governed AI SaaS platforms that notify external systems of substrate events via signed outbound webhook deliveries, and that expose a typed TypeScript SDK enabling external developers to integrate AIEP-governed AI responses into their own applications.

[0004] More particularly, the disclosure concerns: (a) the IntegrationConfig schema with a mandatory content-hashed config_hash field preventing silent mutation of integration configuration; (b) the WebhookEvent union type enumerating the substrate events that may trigger outbound delivery; (c) the dispatch protocol for routing a named event to all active subscribed integrations for a given tenant; and (d) the PieaClient SDK contract covering the /api/ask, /admin/learning-list, and /health endpoints.

Background

[0005] Enterprise AI SaaS platforms must deliver AI-generated outputs to the external tools that users already operate — Slack channels, Microsoft Teams channels, ticketing systems, and internal dashboards. Implementing ad-hoc outbound delivery in application code without a formal integration registry leads to configuration state that cannot be audited, cannot be verified for integrity, and cannot be disabled atomically when a tenant’s permissions change.

[0006] Existing webhook integration approaches store endpoint URLs and secrets in plaintext configuration tables without cryptographic integrity verification of the configuration itself. A configuration record stored in plaintext may be silently mutated to redirect delivery to a different endpoint without detection.

[0007] Application developers who wish to integrate an AI SaaS product into their own workflows require a typed, promise-based TypeScript SDK that handles authentication, request serialisation, and response typing without requiring knowledge of the underlying HTTP route structure.

Summary of the Disclosure

[0008] An IntegrationConfig record comprises: an integration_id derived as the content hash of {tenant_id, endpoint, timestamp}; the tenant_id to which the integration belongs; a type value from the IntegrationType union ("slack" | "teams" | "webhook" | "email"); a human-readable label; a status from IntegrationStatus ("active" | "disabled" | "error"); the outbound endpoint URL or platform connector URL; a signing_secret_ref identifying the Cloudflare Secret that holds the HMAC signing key for payload authentication; a subscribed_events array of WebhookEvent values; created_by and created_at fields; and a config_hash derived as the content hash of {integration_id, type, endpoint}. The config_hash is recomputable from the stored fields — a mismatch on recomputation indicates tampering.

[0009] The WebhookEvent union enumerates the substrate events eligible for outbound delivery:

[0010] The IntegrationRegistry exposes the following operations: add(req: AddIntegrationRequest) — validates request, derives integration_id and config_hash, and stores the IntegrationConfig; getForTenant(tenant_id) — returns all integrations for the specified tenant; getSubscribed(tenant_id, event) — returns active integrations subscribed to a specific event for a given tenant; disable(integration_id) — sets status to "disabled" atomically; and dispatch(tenant_id, event, payload) — routes the event to all subscribed active integrations, records a WebhookDelivery for each, and returns the delivery records.

[0011] Each WebhookDelivery record comprises: a delivery_id derived as the content hash of {integration_id, event, timestamp}; the integration_id; the event name; a payload_hash computed over the outbound payload; a delivered_at ISO 8601 timestamp; and a status of "delivered" or "failed". Failed deliveries must not be silently discarded — they must be persisted to the delivery log regardless of the delivery outcome.

[0012] The PieaClient SDK is initialised with a PieaClientConfig comprising baseUrl (e.g. https://api.piea.ai), apiKey (tenant API key), and tenantId. It exposes:

• ask(req: AskRequest): Promise<AskResponse> — sends a POST to /api/ask with X-Piea-Api-Key and X-Piea-Tenant headers; returns a typed AskResponse
• addSource(url, label, category): Promise<unknown> — sends a POST to /admin/learning-list; adds a source to the tenant Learning List
• health(): Promise<{ status: string }> — sends a GET to /health; returns the worker health status

[0013] AskResponse comprises: response_id; answer (prose response string); confidence_tier (one of "verified" | "qualified" | "indicative" | "unverified"); evidence_rail (array of { artefact_id, source_url, confidence_tier } records); model_used; and timestamp.

Detailed Description

[0014] IntegrationConfig Interface:

interface IntegrationConfig {
  integration_id: string;
  tenant_id: string;
  type: "slack" | "teams" | "webhook" | "email";
  label: string;
  status: "active" | "disabled" | "error";
  endpoint: string;             // Slack webhook URL / Teams connector / HTTP endpoint
  signing_secret_ref: string;   // Cloudflare Secret name — not the secret value
  subscribed_events: WebhookEvent[];
  created_by: string;
  created_at: string;           // ISO 8601
  config_hash: string;          // content_hash({integration_id, type, endpoint})
}

[0015] PieaClient Interface:

interface PieaClientConfig {
  baseUrl: string;   // e.g. https://api.piea.ai
  apiKey: string;
  tenantId: string;
}

interface AskRequest {
  question: string;
  sessionId?: string;
}

interface AskResponse {
  response_id: string;
  answer: string;
  confidence_tier: string;
  evidence_rail: Array<{
    artefact_id: string;
    source_url: string;
    confidence_tier: string;
  }>;
  model_used: string;
  timestamp: string;
}

[0016] Signing Secret Reference Pattern. The signing_secret_ref field stores the name of a Cloudflare Secret — not its value. The actual HMAC signing key is resolved at dispatch time from env[config.signing_secret_ref]. This indirection ensures that: (a) the secret value is never written to the D1 database; (b) rotating the secret requires only a wrangler secret put operation without modifying the integration record; and (c) an audit of the integration record reveals whether a signing key is configured without exposing the key.

[0017] Config Hash Integrity. The config_hash is reproducible from the stored integration_id, type, and endpoint fields using the AIEP content_hash() function. Implementers may verify at audit time that the stored config_hash matches the recomputed value. A mismatch indicates that the endpoint, type, or integration ID has been modified outside the registry’s add() procedure.

[0018] Delivery Log Retention. The delivery log produced by dispatch() must be persisted to the AIEP Evidence Ledger (D1). This ensures that the history of every outbound event delivery — including failed deliveries — is governed by the same append-only, hash-bound ledger that governs evidence artefacts. A delivery record may not be deleted or modified after insertion.

[0019] SDK Authentication. The PieaClient transmits X-Piea-Api-Key and X-Piea-Tenant as request headers on every call. The worker verifies the API key by computing HMAC-SHA256(apiKey, env.PIEA_API_KEY_SECRET) and comparing against the stored hash in the api_keys table (see P130 §10). The raw API key value is not retained server-side after verification.

[0020] Distinction from P125 (Subscription Billing Protocol). P125 specifies the Stripe-based subscription billing lifecycle — plan activation, webhook verification, and tenant entitlement updates. P131 specifies the integration subscription model — tenant configuration of outbound event delivery channels and the developer SDK for programmatic access. Both share the concept of a subscription but operate on orthogonal concerns: billing vs. event routing.