AILANG Packages

Curated AILANG packages for production use. Extracted from real projects (docparse, e-commerce demos, streaming agents) to eliminate duplication and provide tested, reusable modules.

This is a monorepo — multiple packages live in one repository. Each package in packages/ has its own ailang.toml manifest. You can depend on individual packages via path deps or git deps with subdir.

Quick Start

Option 1: Git dependency (recommended — version pinned)

ailang init package --name myorg/myapp
ailang add --git https://github.com/sunholo-data/ailang-packages --subdir packages/auth --tag main
ailang lock

Option 2: Clone + path dependency (for local development)

git clone https://github.com/sunholo-data/ailang-packages.git
cd my-project
ailang add --path ../ailang-packages/packages/auth
ailang lock

Then in your .ail files:

import pkg/sunholo/gcp-auth/token (getAccessToken)
import pkg/sunholo/logging/logger (info, logError)

export func main() -> () ! {IO, FS, Net} =
  match getAccessToken() {
    Ok(token) => info("Authenticated successfully"),
    Err(e) => logError("Auth failed", e)
  }

Available Packages

Package	Description	Effects	AGENT.md
sunholo/gcp-auth	GCP ADC OAuth2 token exchange, project detection	FS, Net	Guide
sunholo/auth	API key validation, HMAC hashing, bearer token extraction	Pure	Guide
sunholo/http-helpers	HTTP request builders, auth headers, JSON response parsing	Net	Guide
sunholo/logging	Structured JSON logging (Cloud Run friendly)	IO	Guide
sunholo/config	Config loading from env vars with validation	Env	Guide
sunholo/testing-utils	Test assertion helpers (assertEqual, assertOk, etc.)	Pure	Guide
sunholo/firestore	Firestore REST API client — CRUD, queries, field encoding	Net, FS, Env	Guide

Billing Packages (DocParse)

Package	Description	Effects	AGENT.md
sunholo/billing_entitlements	Plan catalog, entitlement resolution, quota checks, usage deltas	Pure	Guide
sunholo/billing_proposals	Payment proposal lifecycle for AI-assisted and human billing	Pure	Guide
sunholo/billing_store	Firestore CRUD for billing records (customers, subscriptions, usage)	Net, FS, Env	Guide
sunholo/billing_stripe	Stripe adapter: checkout, portal, webhooks, event mapping	Net, Env	Guide
sunholo/billing_service_api	HTTP handlers for billing Cloud Run service	Net, FS, Env, IO	Guide
sunholo/external_backend	Run external subprocesses that emit JSON; typed Result errors with stderr capture	Process	Guide

AGENT.md — AI Discovery

Each package includes an AGENT.md file — a structured guide for AI agents explaining:

• When to use the package
• Quick start code example
• Exported functions table with signatures
• Common patterns and integration advice

AI agents: read the AGENT.md for any package you add as a dependency.

Monorepo Structure

This repo contains multiple packages. Use subdir to select specific packages:

ailang-packages/
  packages/
    auth/           # sunholo/auth
    gcp-auth/       # sunholo/gcp-auth (depends on auth)
    http-helpers/   # sunholo/http-helpers
    logging/        # sunholo/logging
    config/         # sunholo/config
    testing-utils/  # sunholo/testing-utils
    firestore/      # sunholo/firestore
    billing-entitlements/  # sunholo/billing_entitlements
    billing-proposals/     # sunholo/billing_proposals
    billing-store/         # sunholo/billing_store
    billing-stripe/        # sunholo/billing_stripe
    billing-service-api/   # sunholo/billing_service_api

Using git deps with subdir

[dependencies]
"sunholo/auth" = { git = "https://github.com/sunholo-data/ailang-packages", subdir = "packages/auth", tag = "main" }
"sunholo/logging" = { git = "https://github.com/sunholo-data/ailang-packages", subdir = "packages/logging", tag = "main" }

The AILANG package system supports multiple packages per repo via the subdir field. You don't need one repo per package.

How It Works

Each package has an ailang.toml manifest declaring its name, exports, effects, and dependencies. The ailang.lock file pins content hashes for reproducible builds.

Two dependency modes:

• Path deps ({ path = "../..." }) — local, for development
• Git deps ({ git = "url", subdir = "...", tag = "..." }) — remote, version-pinned

Contributing

To add a package:

1. Create packages/your-package/ailang.toml with sunholo/name format
2. Add .ail source files with module sunholo/name/module declarations
3. Use underscores in module paths (not hyphens): sunholo/billing_store, not sunholo/billing-store
4. Use export type for any types other packages will use: export type MyRecord = { ... }
5. Use pkg/ prefix for all imports — including siblings within the same package
6. List exported modules in [exports].modules
7. Declare max effects in [effects].max
8. Add ai_summary in [metadata] for agent discovery
9. Write AGENT.md with usage guide for AI agents
10. Validate: ailang lock && ailang check --package .
11. Test with ailang add --path or ailang add --git from a test project

Critical Conventions

-- Module names use underscores (directory can have hyphens)
module sunholo/billing_store/customers_repo

-- Import Ok/Err explicitly (not in prelude)
import std/result (Ok, Err)

-- Use ./ for siblings in SAME package (preferred)
import ./entitlements_repo (getEntitlements)

-- Use pkg/ for EXTERNAL package dependencies
import pkg/sunholo/firestore/client (getDoc, setDoc)

-- Export types that other packages will reference
export type Customer = { name: string, email: string }