Akadli-AI

Developer & Agent Quickstart

For Human Developers

1. Install Core & Adapter

pnpm add @akadli/core @akadli/dz-geo @akadli/provider-shopify

2. Ingest Webhook, Trigger Voice Call & Mutate Order

import { ShopifyProvider } from "@akadli/provider-shopify";
import { handleFinalizeOrderToolCall, buildElevenAgentsDynamicVariables } from "@akadli/core";

const provider = new ShopifyProvider();

// 1. Verify HMAC signature & parse order into 2026 69-Wilaya format
const isValid = await provider.verifyWebhook(headers, rawBody, process.env.SHOPIFY_WEBHOOK_SECRET!);
const order = await provider.parseWebhookOrder(JSON.parse(rawBody));

// 2. Build ElevenAgents dynamic variables (currentVariant, allowedVariants, phone)
const promptVars = buildElevenAgentsDynamicVariables(order);

// 3. Receive tool call from ElevenLabs after call and apply store mutation
const result = await handleFinalizeOrderToolCall(
  {
    orderId: order.orderId,
    status: "CONFIRMED", // or "MODIFIED" (finalVariant, finalCommune) | "REFUSED"
    reasonOrNotes: "Confirmed in Algerian Darja via ElevenAgents"
  },
  provider,
  { shopDomain: process.env.SHOPIFY_SHOP_DOMAIN!, accessToken: process.env.SHOPIFY_ACCESS_TOKEN! },
  order.constraints
);

For AI Coding Agents

Zero-Friction Agent Context

Give your AI assistant (Cursor, Antigravity, Claude Code, GitHub Copilot) instant access to the entire Akadli-AI architecture:

• Compact Spec: https://akadli.me/llms.txt
• Complete Ecosystem Bundle: https://akadli.me/llms-full.txt

Agent System Prompt

Copy and paste this prompt directly into your agent instructions or composer:

You are integrating the Akadli-AI voice confirmation engine for Algerian Cash-on-Delivery (COD).
Fetch context from https://akadli.me/llms-full.txt and adhere strictly to these rules:
1. Use @akadli/adapter-contract for StandardizedDzOrder and FinalizedOrderDecision.
2. Normalize Algerian addresses to the 2026 69-Wilaya division with @akadli/dz-geo.
3. Use @akadli/core to generate ElevenAgents prompt variables and execute handleFinalizeOrderToolCall.
4. Store tags MUST follow: akadli-confirmed, akadli-modified, akadli-refused, and akadli-variant-{variant}.
5. Order notes MUST be prefixed with [Akadli-AI].
6. Never invent ad-hoc status strings; use CONFIRMED, REFUSED, or MODIFIED.

---

Architectural Highlights

2026 69 Wilayas & 1,708 Communes

Official Algerian administrative division with Arabic, French, and Arabizi fuzzy address resolution. Includes newly promoted Wilayas (59–69 like Barika, Bou Saada, Bir El Ater).

ElevenAgents Voice Orchestration

Stateless WebRTC & SIP audio bridge. Generates Darja-tailored system prompt variables and securely validates final decisions via server-side tool calls.

Production Store Adapters

Ready-to-use stateless connectors for Shopify, YouCan, WooCommerce, Google Sheets (SetShop/JustSell), and Tassyir COD ERP with Ed25519 signature checks.

Local Wi-Fi Testing Sandbox

Interactive @akadli/playground with a desktop dispatch center (/admin) and a mobile phone simulator (/phone) for live testing over LAN without deploying servers.

---

Packages & Modules

Module	Package	Description	Guide
Adapter Contract	@akadli/adapter-contract	Domain models, Zod validation schemas & provider interface	Overview
Algerian Geography	@akadli/dz-geo	2026 69 Wilayas, 1,708 Communes & +213 phone normalizer	Overview
Voice Engine	@akadli/core	Dynamic prompt variables & post-call decision orchestrator	Overview
Shopify	@akadli/provider-shopify	HMAC verification, missing-province resolution & order mutations	Guide
YouCan	@akadli/provider-youcan	1-page checkout extra_fields extraction & order updates	Guide
WooCommerce	@akadli/provider-woocommerce	REST v3 Basic Auth, DZ-XX states & COD plugin meta_data	Guide
Google Sheets	@akadli/provider-gsheets	Universal Sheets v4 & Zero-OAuth Apps Script bridge	Guide
Tassyir ERP	@akadli/provider-tassyir	Admin API (2026-10), Ed25519 webhooks & OAuth install codes	Guide