acl-core-ts 1.75.1

package/LICENSE

@@ -0,0 +1,24 @@
+ACL SDK PROPRIETARY LICENSE
+Copyright (c) 2026 ACL Team. All rights reserved.
+
+This SDK is proprietary software and is licensed, not sold.
+
+Permitted use:
+- Use only to access ACL services with a valid ACL-issued API key.
+- Internal use by authorized users and systems under your organization.
+
+Not permitted without prior written permission from ACL Team:
+- Redistribute, sublicense, resell, rent, lease, or transfer this SDK.
+- Modify, create derivative works, reverse engineer, decompile, or disassemble this SDK.
+- Use this SDK to build or operate a competing service.
+
+No open-source grant:
+- No rights are granted under any open-source license.
+
+Termination:
+- Any violation of these terms immediately terminates your license to use this SDK.
+
+Disclaimer:
+- The SDK is provided "as is" without warranties of any kind, to the maximum extent permitted by law.
+
+For commercial or redistribution permissions, contact: support@fridayaicore.in

package/README.md

@@ -0,0 +1,129 @@
+# ACL TypeScript SDK (`acl-core-ts`)
+
+Official TypeScript SDK for Adaptive Context Layer (ACL).
+
+## Installation
+
+```bash
+npm install acl-core-ts
+```
+
+## AI Agent Install And Infra Setup
+
+Use this flow when agents/dev tools install and run ACL in production:
+
+1. Install SDK
+
+```bash
+npm install acl-core-ts@latest
+```
+
+2. Set environment variables (domain only, never raw server IP)
+
+```bash
+# 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
+
+```ts
+import { ACLClient } from 'acl-core-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
+
+```ts
+import { ACLClient } from 'acl-core-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.75.1)
+
+`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`.

package/dist/client.d.ts

@@ -0,0 +1,51 @@
+import { AdaptiveWindowParams, ACLClientOptions, AdaptiveResponse, ACLTelemetry, CompleteResponse, CompleteParams } from './types';
+import { BaseProvider } from './providers/base';
+import { SessionPolicy } from './session/manager';
+export declare class ACLClient {
+    private readonly config;
+    private readonly httpClient;
+    private isClosed;
+    private readonly sessionManager;
+    private readonly middlewares;
+    private readonly defaultMaxRetries;
+    private readonly secureLogging;
+    private readonly emitPostCompletionTelemetry;
+    private readonly precheckCacheTtlMs;
+    private readonly precheckCacheMaxEntries;
+    private readonly precheckCache;
+    constructor(options: ACLClientOptions & {
+        sessionPolicy?: SessionPolicy;
+        sessionLimit?: number;
+    });
+    registerProvider(name: string, providerClass: new () => BaseProvider): void;
+    adaptiveWindow(params: AdaptiveWindowParams & {
+        integration_mode?: string;
+    }): Promise<AdaptiveResponse>;
+    complete(params: CompleteParams): Promise<CompleteResponse>;
+    private _detectClientModel;
+    getProviderMetadata(): Promise<any>;
+    getTelemetry(response: any): ACLTelemetry;
+    close(): void;
+    closeAllSessions(): void;
+    closeSession(sessionId: string): void;
+    private validateCompleteInputs;
+    private validateProviderKey;
+    private getProviderParams;
+    private errorCodeFromError;
+    private buildErrorResponse;
+    private ensureNotClosed;
+    private _syncInternalState;
+    private attachTimingMetadata;
+    private buildPrecheckCacheKey;
+    private hashPrompt;
+    private getCachedPrecheck;
+    private setCachedPrecheck;
+    private getPrecheckResponse;
+    private dispatchCompletionTelemetry;
+    private syncCompletionTelemetry;
+    private emitRecoveryEvents;
+    private buildProviderMetadata;
+    private postEvent;
+    private requestLoopVerdict;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACf,MAAM,SAAS,CAAC;AAIjB,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEhD,OAAO,EAAkB,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAQlE,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;IAC1C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;IACxC,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAiB;IAChD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAkB;IAC9C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAU;IACxC,OAAO,CAAC,QAAQ,CAAC,2BAA2B,CAAU;IACtD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAC5C,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAS;IACjD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAiE;gBAEnF,OAAO,EAAE,gBAAgB,GAAG;QAAE,aAAa,CAAC,EAAE,aAAa,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE;IAqDzF,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,UAAU,YAAY,GAAG,IAAI;IAQ5E,cAAc,CAAC,MAAM,EAAE,oBAAoB,GAAG;QAAE,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAevG,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA+LjE,OAAO,CAAC,kBAAkB;IA4BpB,mBAAmB,IAAI,OAAO,CAAC,GAAG,CAAC;IAezC,YAAY,CAAC,QAAQ,EAAE,GAAG,GAAG,YAAY;IAWzC,KAAK,IAAI,IAAI;IAKb,gBAAgB,IAAI,IAAI;IAOxB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAIrC,OAAO,CAAC,sBAAsB;IAwC9B,OAAO,CAAC,mBAAmB;IAkB3B,OAAO,CAAC,iBAAiB;IA+BzB,OAAO,CAAC,kBAAkB;IAQ1B,OAAO,CAAC,kBAAkB;IA2B1B,OAAO,CAAC,eAAe;IAUvB,OAAO,CAAC,kBAAkB;IAU1B,OAAO,CAAC,oBAAoB;IAgB5B,OAAO,CAAC,qBAAqB;IAS7B,OAAO,CAAC,UAAU;IASlB,OAAO,CAAC,iBAAiB;IAYzB,OAAO,CAAC,iBAAiB;YAaX,mBAAmB;IAcjC,OAAO,CAAC,2BAA2B;YAOrB,uBAAuB;YA0CvB,kBAAkB;IAkChC,OAAO,CAAC,qBAAqB;YAYf,SAAS;YAST,kBAAkB;CASjC"}