ACL TypeScript SDK (acl-layer-ts)

Official TypeScript SDK for Adaptive Context Layer (ACL).

Installation

npm install acl-layer-ts

AI Agent Install And Infra Setup

Use this flow when agents/dev tools install and run ACL in production:

1. Install SDK

npm install acl-layer-ts@latest

2. Set environment variables (domain only, never raw server IP)

# Public ACL endpoint behind your domain/reverse proxy
export ACL_BASE_URL="https://backend.yourcompany.com"

# Org-scoped ACL key from ACL dashboard
export ACL_API_KEY="acl_live_xxx"

# Provider key stays only with your app/agent runtime
export OPENAI_API_KEY="sk-xxx"

3. Initialize client using env vars

import { ACLClient } from 'acl-layer-ts';

const client = new ACLClient({
  apiKey: process.env.ACL_API_KEY!,
  baseUrl: process.env.ACL_BASE_URL!,
});

Security notes:

• Do not hardcode keys in source code.
• Do not expose EC2/public IP in SDK config; always use DNS/domain.
• Rotate keys immediately if logs/screenshots accidentally leak them.
• Keep backend behind TLS (https) and firewall to trusted ports only.

Quick Start

import { ACLClient } from 'acl-layer-ts';

const client = new ACLClient({ apiKey: 'acl_live_...' });

const result = await client.complete({
  prompt: 'Summarize this incident report.',
  model: 'gpt-4o',
  llm_api_key: 'sk-...',
  max_retries: 3,
});

if (result.success) {
  console.log(result.response);
} else {
  console.error(`${result.error_code}: ${result.error_message}`);
}

Latency Controls (v1.8.5)

new ACLClient(...) supports these runtime options:

• emitPostCompletionTelemetry (default: true): post-completion telemetry is non-blocking.
• precheckCacheTtlMs (default: 20000): short TTL cache for adaptive precheck calls.
• precheckCacheMaxEntries (default: 256): max in-memory precheck cache entries.

Every complete() response now includes timing metadata under metadata.acl_timing:

• precheck_ms
• provider_ms
• post_telemetry_ms
• wall_clock_ms

Runtime Contract

complete() always returns a stable top-level response shape on both success and failure:

• success
• error_code
• error_message
• provider
• model
• text and response

Validation and Safety

• Fail-fast validation for invalid/missing prompt, unresolved model, missing keys, and malformed provider key formats.
• Strict provider payload allowlist prevents internal ACL params from leaking to provider APIs.
• Secrets are redacted from surfaced error messages by default.
• Production default ACL base URL is http://backend.fridayaicore.in.

Retry Behavior

• Retries happen in SDK provider execution middleware (complete() path).
• Exponential backoff with jitter and cap:
• attempt 1: random delay 0-0.5s
• attempt 2: random delay 0-1s
• attempt 3: random delay 0-2s
• max cap per attempt: 8s

Compatibility Policy

• Node.js: >=16
• Module output: CommonJS (dist/index.js)
• Types: bundled .d.ts in dist/
• Release policy: include migration notes whenever response contract or validation behavior changes.

Usage Terms

• This SDK is proprietary and licensed for ACL service access only.
• A valid ACL API key is required.
• Redistribution, resale, sublicensing, and derivative redistribution are not permitted without written approval from ACL Team.

License

UNLICENSED / Proprietary. See LICENSE.