@caracalai/core 0.1.0 → 0.1.1

package/dist/cliconfig.d.ts

@@ -1,3 +1,4 @@
+import { CaracalError } from './errors.js';
 export declare const DEFAULT_API_URL = "http://localhost:3000";
 export declare const DEFAULT_COORDINATOR_URL = "http://localhost:4000";
 export interface Credential {
@@ -21,7 +22,7 @@ export interface CliConfig {
     mcp_governance?: McpGovernance;
 }
 export declare function resolveCliConfigPath(env?: NodeJS.ProcessEnv): string | undefined;
-export declare class ServiceUrlMissingError extends Error {
+export declare class ServiceUrlMissingError extends CaracalError {
     readonly envKey: string;
     readonly nodeEnv: string;
     constructor(envKey: string, nodeEnv: string);

package/dist/cliconfig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cliconfig.d.ts","sourceRoot":"","sources":["../src/cliconfig.ts"],"names":[],"mappings":"AASA,eAAO,MAAM,eAAe,0BAA0B,CAAC;AACvD,eAAO,MAAM,uBAAuB,0BAA0B,CAAC;AAE/D,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,kBAAmB,SAAQ,UAAU;IACpD,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,OAAO,GAAG,KAAK,CAAC;CACvB;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;IAC3B,oBAAoB,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAC5C,cAAc,CAAC,EAAE,aAAa,CAAC;CAChC;AAKD,wBAAgB,oBAAoB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,GAAG,SAAS,CAc7F;AAED,qBAAa,sBAAuB,SAAQ,KAAK;aACnB,MAAM,EAAE,MAAM;aAAkB,OAAO,EAAE,MAAM;gBAA/C,MAAM,EAAE,MAAM,EAAkB,OAAO,EAAE,MAAM;CAI5E;AAID,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAQ5E"}
+{"version":3,"file":"cliconfig.d.ts","sourceRoot":"","sources":["../src/cliconfig.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,eAAO,MAAM,eAAe,0BAA0B,CAAC;AACvD,eAAO,MAAM,uBAAuB,0BAA0B,CAAC;AAE/D,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,kBAAmB,SAAQ,UAAU;IACpD,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,OAAO,GAAG,KAAK,CAAC;CACvB;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;IAC3B,oBAAoB,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAC5C,cAAc,CAAC,EAAE,aAAa,CAAC;CAChC;AAKD,wBAAgB,oBAAoB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,GAAG,SAAS,CAc7F;AAED,qBAAa,sBAAuB,SAAQ,YAAY;IACtD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBACb,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAQ5C;AAID,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAQ5E"}

package/dist/cliconfig.js

@@ -5,6 +5,7 @@
 import { existsSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { CaracalError } from './errors.js';
 export const DEFAULT_API_URL = 'http://localhost:3000';
 export const DEFAULT_COORDINATOR_URL = 'http://localhost:4000';
 // Resolves the path to caracal.toml using the documented precedence:
@@ -28,14 +29,16 @@ export function resolveCliConfigPath(env = process.env) {
     }
     return undefined;
 }
-export class ServiceUrlMissingError extends Error {
+export class ServiceUrlMissingError extends CaracalError {
     envKey;
     nodeEnv;
     constructor(envKey, nodeEnv) {
-        super(`${envKey} is required when NODE_ENV=${nodeEnv}`);
+        super('config_missing', `${envKey} is required when NODE_ENV=${nodeEnv}`, {
+            details: { envKey, nodeEnv },
+        });
+        this.name = 'ServiceUrlMissingError';
         this.envKey = envKey;
         this.nodeEnv = nodeEnv;
-        this.name = 'ServiceUrlMissingError';
     }
 }
 // Returns the env-var override or the dev default. Throws ServiceUrlMissingError

package/dist/cliconfig.js.map

@@ -1 +1 @@
-{"version":3,"file":"cliconfig.js","sourceRoot":"","sources":["../src/cliconfig.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,qCAAqC;AACrC,EAAE;AACF,6EAA6E;AAE7E,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,MAAM,CAAC,MAAM,eAAe,GAAG,uBAAuB,CAAC;AACvD,MAAM,CAAC,MAAM,uBAAuB,GAAG,uBAAuB,CAAC;AA0B/D,qEAAqE;AACrE,sGAAsG;AACtG,sDAAsD;AACtD,MAAM,UAAU,oBAAoB,CAAC,MAAyB,OAAO,CAAC,GAAG;IACvE,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,IAAI,GAAG,CAAC,cAAc;QAAE,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAC5D,KAAK,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;QACzD,IAAI,GAAG;YAAE,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC,CAAC;IACtD,CAAC;IACD,MAAM,GAAG,GAAG,GAAG,CAAC,eAAe,IAAI,GAAG,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC;QAC/D,CAAC,CAAC,GAAG,CAAC,eAAe;QACrB,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,CAAC,CAAC;IAC/B,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,EAAE,cAAc,CAAC,CAAC,CAAC;IACtD,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC9B,IAAI,UAAU,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;IACpC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IACnB;IAAgC;IAA5D,YAA4B,MAAc,EAAkB,OAAe;QACzE,KAAK,CAAC,GAAG,MAAM,8BAA8B,OAAO,EAAE,CAAC,CAAC;QAD9B,WAAM,GAAN,MAAM,CAAQ;QAAkB,YAAO,GAAP,OAAO,CAAQ;QAEzE,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AAED,iFAAiF;AACjF,sFAAsF;AACtF,MAAM,UAAU,iBAAiB,CAAC,MAAc,EAAE,UAAkB;IAClE,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC9B,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IAChB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,aAAa,CAAC;IAClD,IAAI,GAAG,KAAK,aAAa,EAAE,CAAC;QAC1B,MAAM,IAAI,sBAAsB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAChD,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC"}
+{"version":3,"file":"cliconfig.js","sourceRoot":"","sources":["../src/cliconfig.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,qCAAqC;AACrC,EAAE;AACF,6EAA6E;AAE7E,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,CAAC,MAAM,eAAe,GAAG,uBAAuB,CAAC;AACvD,MAAM,CAAC,MAAM,uBAAuB,GAAG,uBAAuB,CAAC;AA0B/D,qEAAqE;AACrE,sGAAsG;AACtG,sDAAsD;AACtD,MAAM,UAAU,oBAAoB,CAAC,MAAyB,OAAO,CAAC,GAAG;IACvE,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,IAAI,GAAG,CAAC,cAAc;QAAE,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAC5D,KAAK,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;QACzD,IAAI,GAAG;YAAE,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC,CAAC;IACtD,CAAC;IACD,MAAM,GAAG,GAAG,GAAG,CAAC,eAAe,IAAI,GAAG,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC;QAC/D,CAAC,CAAC,GAAG,CAAC,eAAe;QACrB,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,CAAC,CAAC;IAC/B,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,EAAE,cAAc,CAAC,CAAC,CAAC;IACtD,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC9B,IAAI,UAAU,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;IACpC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,OAAO,sBAAuB,SAAQ,YAAY;IAC7C,MAAM,CAAS;IACf,OAAO,CAAS;IACzB,YAAY,MAAc,EAAE,OAAe;QACzC,KAAK,CAAC,gBAAgB,EAAE,GAAG,MAAM,8BAA8B,OAAO,EAAE,EAAE;YACxE,OAAO,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE;SAC7B,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AAED,iFAAiF;AACjF,sFAAsF;AACtF,MAAM,UAAU,iBAAiB,CAAC,MAAc,EAAE,UAAkB;IAClE,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC9B,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IAChB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,aAAa,CAAC;IAClD,IAAI,GAAG,KAAK,aAAa,EAAE,CAAC;QAC1B,MAAM,IAAI,sBAAsB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAChD,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/dist/config.d.ts

@@ -1,11 +1,3 @@
-export interface BaseConfig {
-    port: number;
-    databaseUrl: string;
-    redisUrl: string;
-    stsUrl: string;
-    logLevel: string;
-}
 export declare function mustGetenv(key: string): string;
 export declare function getenv(key: string, fallback: string): string;
-export declare function loadBaseConfig(): BaseConfig;
 //# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAI9C;AAED,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED,wBAAgB,cAAc,IAAI,UAAU,CAQ3C"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAKA,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAI9C;AAED,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE5D"}

package/dist/config.js

@@ -1,7 +1,7 @@
 // Copyright (C) 2026 Garudex Labs.  All Rights Reserved.
 // Caracal, a product of Garudex Labs
 //
-// Shared configuration loader for TypeScript services.
+// Shared environment variable accessors for TypeScript services.
 export function mustGetenv(key) {
     const v = process.env[key];
     if (!v)
@@ -11,13 +11,4 @@ export function mustGetenv(key) {
 export function getenv(key, fallback) {
     return process.env[key] ?? fallback;
 }
-export function loadBaseConfig() {
-    return {
-        port: parseInt(mustGetenv('PORT'), 10),
-        databaseUrl: mustGetenv('DATABASE_URL'),
-        redisUrl: mustGetenv('REDIS_URL'),
-        stsUrl: getenv('STS_URL', 'http://localhost:8080'),
-        logLevel: getenv('LOG_LEVEL', 'info'),
-    };
-}
 //# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,qCAAqC;AACrC,EAAE;AACF,uDAAuD;AAUvD,MAAM,UAAU,UAAU,CAAC,GAAW;IACpC,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC3B,IAAI,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,6BAA6B,GAAG,EAAE,CAAC,CAAC;IAC5D,OAAO,CAAC,CAAC;AACX,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,GAAW,EAAE,QAAgB;IAClD,OAAO,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,QAAQ,CAAC;AACtC,CAAC;AAED,MAAM,UAAU,cAAc;IAC5B,OAAO;QACL,IAAI,EAAE,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACtC,WAAW,EAAE,UAAU,CAAC,cAAc,CAAC;QACvC,QAAQ,EAAE,UAAU,CAAC,WAAW,CAAC;QACjC,MAAM,EAAE,MAAM,CAAC,SAAS,EAAE,uBAAuB,CAAC;QAClD,QAAQ,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC;KACtC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,qCAAqC;AACrC,EAAE;AACF,iEAAiE;AAEjE,MAAM,UAAU,UAAU,CAAC,GAAW;IACpC,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC3B,IAAI,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,6BAA6B,GAAG,EAAE,CAAC,CAAC;IAC5D,OAAO,CAAC,CAAC;AACX,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,GAAW,EAAE,QAAgB;IAClD,OAAO,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,QAAQ,CAAC;AACtC,CAAC"}

package/dist/env.d.ts

@@ -1,3 +1,5 @@
-export declare function caracalEnv(): string;
-export declare function isProduction(): boolean;
+export type CaracalMode = 'dev' | 'runtime';
+export declare function caracalMode(): CaracalMode;
+export declare function isRuntime(): boolean;
+export declare function assertRuntimeSafe(): void;
 //# sourceMappingURL=env.d.ts.map

package/dist/env.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAKA,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED,wBAAgB,YAAY,IAAI,OAAO,CAGtC"}
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,SAAS,CAAC;AAE5C,wBAAgB,WAAW,IAAI,WAAW,CAKzC;AAED,wBAAgB,SAAS,IAAI,OAAO,CAEnC;AAED,wBAAgB,iBAAiB,IAAI,IAAI,CAUxC"}

package/dist/env.js

@@ -2,11 +2,27 @@
 // Caracal, a product of Garudex Labs
 //
 // Shared environment classification for TypeScript services.
-export function caracalEnv() {
-    return process.env.CARACAL_ENV ?? 'development';
+export function caracalMode() {
+    const raw = (process.env.CARACAL_MODE ?? '').trim().toLowerCase();
+    if (raw === '' || raw === 'runtime')
+        return 'runtime';
+    if (raw === 'dev')
+        return 'dev';
+    throw new Error(`CARACAL_MODE must be 'dev' or 'runtime' (got '${raw}')`);
 }
-export function isProduction() {
-    const env = caracalEnv();
-    return env === 'production' || env === 'prod' || env === 'staging';
+export function isRuntime() {
+    return caracalMode() === 'runtime';
+}
+export function assertRuntimeSafe() {
+    if (caracalMode() !== 'runtime')
+        return;
+    const forbidden = ['INSECURE_STS', 'INSECURE_HTTP', 'CARACAL_LOCAL_BOOTSTRAP_ENABLED'];
+    const set = forbidden.filter((k) => {
+        const v = (process.env[k] ?? '').toLowerCase();
+        return v === 'true' || v === '1' || v === 'yes';
+    });
+    if (set.length > 0) {
+        throw new Error(`CARACAL_MODE=runtime forbids: ${set.join(', ')}`);
+    }
 }
 //# sourceMappingURL=env.js.map

package/dist/env.js.map

@@ -1 +1 @@
-{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,qCAAqC;AACrC,EAAE;AACF,6DAA6D;AAE7D,MAAM,UAAU,UAAU;IACxB,OAAO,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,aAAa,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,YAAY;IAC1B,MAAM,GAAG,GAAG,UAAU,EAAE,CAAC;IACzB,OAAO,GAAG,KAAK,YAAY,IAAI,GAAG,KAAK,MAAM,IAAI,GAAG,KAAK,SAAS,CAAC;AACrE,CAAC"}
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,qCAAqC;AACrC,EAAE;AACF,6DAA6D;AAI7D,MAAM,UAAU,WAAW;IACzB,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAClE,IAAI,GAAG,KAAK,EAAE,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACtD,IAAI,GAAG,KAAK,KAAK;QAAE,OAAO,KAAK,CAAC;IAChC,MAAM,IAAI,KAAK,CAAC,iDAAiD,GAAG,IAAI,CAAC,CAAC;AAC5E,CAAC;AAED,MAAM,UAAU,SAAS;IACvB,OAAO,WAAW,EAAE,KAAK,SAAS,CAAC;AACrC,CAAC;AAED,MAAM,UAAU,iBAAiB;IAC/B,IAAI,WAAW,EAAE,KAAK,SAAS;QAAE,OAAO;IACxC,MAAM,SAAS,GAAG,CAAC,cAAc,EAAE,eAAe,EAAE,iCAAiC,CAAC,CAAC;IACvF,MAAM,GAAG,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;QACjC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;QAC/C,OAAO,CAAC,KAAK,MAAM,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,KAAK,CAAC;IAClD,CAAC,CAAC,CAAC;IACH,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CAAC,iCAAiC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACrE,CAAC;AACH,CAAC"}

package/dist/errors.d.ts

@@ -1,9 +1,17 @@
-export type ErrorCode = 'access_denied' | 'invalid_token' | 'resource_not_found' | 'internal_error' | 'policy_eval_failed' | 'provider_rate_limited' | 'interaction_required' | 'sts_unavailable' | 'credential_expired_not_renewable' | 'payload_too_large';
+export type WellKnownErrorCode = 'access_denied' | 'invalid_token' | 'resource_not_found' | 'internal_error' | 'policy_eval_failed' | 'provider_rate_limited' | 'interaction_required' | 'sts_unavailable' | 'credential_expired_not_renewable' | 'payload_too_large' | 'zone_invalid' | 'scope_insufficient' | 'agent_identity_required' | 'delegation_required' | 'chain_mismatch' | 'hop_count_exceeded' | 'http_request_failed' | 'config_missing';
+export type ErrorCode = WellKnownErrorCode | (string & {});
+export interface CaracalErrorOptions {
+    requestId?: string;
+    details?: Record<string, unknown>;
+    cause?: unknown;
+}
 export declare class CaracalError extends Error {
     readonly code: ErrorCode;
-    readonly requestId?: string | undefined;
-    constructor(code: ErrorCode, message: string, requestId?: string | undefined);
+    readonly requestId?: string;
+    readonly details?: Record<string, unknown>;
+    constructor(code: ErrorCode, message: string, opts?: CaracalErrorOptions | string);
     toJSON(): {
+        details?: Record<string, unknown> | undefined;
         requestId?: string | undefined;
         error: ErrorCode;
         error_description: string;

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,SAAS,GACjB,eAAe,GACf,eAAe,GACf,oBAAoB,GACpB,gBAAgB,GAChB,oBAAoB,GACpB,uBAAuB,GACvB,sBAAsB,GACtB,iBAAiB,GACjB,kCAAkC,GAClC,mBAAmB,CAAC;AAExB,qBAAa,YAAa,SAAQ,KAAK;aAEnB,IAAI,EAAE,SAAS;aAEf,SAAS,CAAC,EAAE,MAAM;gBAFlB,IAAI,EAAE,SAAS,EAC/B,OAAO,EAAE,MAAM,EACC,SAAS,CAAC,EAAE,MAAM,YAAA;IAMpC,MAAM;;;;;CAOP"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,kBAAkB,GAC1B,eAAe,GACf,eAAe,GACf,oBAAoB,GACpB,gBAAgB,GAChB,oBAAoB,GACpB,uBAAuB,GACvB,sBAAsB,GACtB,iBAAiB,GACjB,kCAAkC,GAClC,mBAAmB,GACnB,cAAc,GACd,oBAAoB,GACpB,yBAAyB,GACzB,qBAAqB,GACrB,gBAAgB,GAChB,oBAAoB,GACpB,qBAAqB,GACrB,gBAAgB,CAAC;AAIrB,MAAM,MAAM,SAAS,GAAG,kBAAkB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAE3D,MAAM,WAAW,mBAAmB;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAE/B,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,mBAAmB,GAAG,MAAW;IASrF,MAAM;;;;;;CAQP"}

package/dist/errors.js

@@ -5,17 +5,23 @@
 export class CaracalError extends Error {
     code;
     requestId;
-    constructor(code, message, requestId) {
-        super(message);
-        this.code = code;
-        this.requestId = requestId;
+    details;
+    constructor(code, message, opts = {}) {
+        const options = typeof opts === 'string' ? { requestId: opts } : opts;
+        super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
         this.name = 'CaracalError';
+        this.code = code;
+        if (options.requestId)
+            this.requestId = options.requestId;
+        if (options.details)
+            this.details = options.details;
     }
     toJSON() {
         return {
             error: this.code,
             error_description: this.message,
             ...(this.requestId ? { requestId: this.requestId } : {}),
+            ...(this.details ? { details: this.details } : {}),
         };
     }
 }

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,qCAAqC;AACrC,EAAE;AACF,wDAAwD;AAcxD,MAAM,OAAO,YAAa,SAAQ,KAAK;IAEnB;IAEA;IAHlB,YACkB,IAAe,EAC/B,OAAe,EACC,SAAkB;QAElC,KAAK,CAAC,OAAO,CAAC,CAAC;QAJC,SAAI,GAAJ,IAAI,CAAW;QAEf,cAAS,GAAT,SAAS,CAAS;QAGlC,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;IAED,MAAM;QACJ,OAAO;YACL,KAAK,EAAE,IAAI,CAAC,IAAI;YAChB,iBAAiB,EAAE,IAAI,CAAC,OAAO;YAC/B,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACzD,CAAC;IACJ,CAAC;CACF"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,qCAAqC;AACrC,EAAE;AACF,wDAAwD;AAgCxD,MAAM,OAAO,YAAa,SAAQ,KAAK;IAC5B,IAAI,CAAY;IAChB,SAAS,CAAU;IACnB,OAAO,CAA2B;IAE3C,YAAY,IAAe,EAAE,OAAe,EAAE,OAAqC,EAAE;QACnF,MAAM,OAAO,GAAwB,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;QAC3F,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QACnF,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,OAAO,CAAC,SAAS;YAAE,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QAC1D,IAAI,OAAO,CAAC,OAAO;YAAE,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IACtD,CAAC;IAED,MAAM;QACJ,OAAO;YACL,KAAK,EAAE,IAAI,CAAC,IAAI;YAChB,iBAAiB,EAAE,IAAI,CAAC,OAAO;YAC/B,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACxD,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACnD,CAAC;IACJ,CAAC;CACF"}

package/dist/index.d.ts

@@ -5,4 +5,5 @@ export * from './envfile.js';
 export * from './errors.js';
 export * from './logging.js';
 export * from './scope.js';
+export * from './url.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC"}

package/dist/index.js

@@ -9,4 +9,5 @@ export * from './envfile.js';
 export * from './errors.js';
 export * from './logging.js';
 export * from './scope.js';
+export * from './url.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,qCAAqC;AACrC,EAAE;AACF,gFAAgF;AAEhF,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,qCAAqC;AACrC,EAAE;AACF,gFAAgF;AAEhF,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC"}

package/dist/url.d.ts

@@ -0,0 +1,3 @@
+/** Strips the query string (`?…`) from a URL or path fragment. */
+export declare function pathOnly(url: string): string;
+//# sourceMappingURL=url.d.ts.map

package/dist/url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url.d.ts","sourceRoot":"","sources":["../src/url.ts"],"names":[],"mappings":"AAKA,kEAAkE;AAClE,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAG5C"}

package/dist/url.js

@@ -0,0 +1,10 @@
+// Copyright (C) 2026 Garudex Labs.  All Rights Reserved.
+// Caracal, a product of Garudex Labs
+//
+// Minimal URL helpers for server `req.url`-style paths (pathname + optional query).
+/** Strips the query string (`?…`) from a URL or path fragment. */
+export function pathOnly(url) {
+    const q = url.indexOf('?');
+    return q === -1 ? url : url.slice(0, q);
+}
+//# sourceMappingURL=url.js.map

package/dist/url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"url.js","sourceRoot":"","sources":["../src/url.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,qCAAqC;AACrC,EAAE;AACF,oFAAoF;AAEpF,kEAAkE;AAClE,MAAM,UAAU,QAAQ,CAAC,GAAW;IAClC,MAAM,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IAC1B,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;AACzC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caracalai/core",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Caracal SDK foundation: logging, config, errors.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/Garudex-Labs/caracal",
@@ -9,7 +9,12 @@
     "url": "https://github.com/Garudex-Labs/caracal.git",
     "directory": "packages/core/ts"
   },
-  "keywords": ["caracal", "agent", "identity", "sdk"],
+  "keywords": [
+    "caracal",
+    "agent",
+    "identity",
+    "sdk"
+  ],
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -23,8 +28,14 @@
       "types": "./dist/cliconfig.d.ts"
     }
   },
-  "files": ["dist", "README.md", "LICENSE"],
-  "publishConfig": { "access": "public" },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
@@ -33,8 +44,8 @@
     "prepublishOnly": "tsc"
   },
   "devDependencies": {
-    "@types/node": "^24.0.0",
-    "typescript": "^5.8.0",
-    "vitest": "^3.0.0"
+    "@types/node": "^24.12.2",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6"
   }
 }