@caracalai/sdk 0.1.2 → 0.1.4-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -4,5 +4,5 @@ export * from "./coordinator.js";
4
4
  export * from "./primitives.js";
5
5
  export * from "./http.js";
6
6
  export { Caracal } from "./client.js";
7
- export type { CaracalConfig, SpawnOptions, DelegateOptions, LifecycleHook } from "./client.js";
7
+ export type { CaracalConfig, SpawnOptions, DelegateOptions, LifecycleHook, RootOptions, TokenSource, ClientSecretOptions } from "./client.js";
8
8
  //# sourceMappingURL=advanced.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"advanced.d.ts","sourceRoot":"","sources":["../src/advanced.ts"],"names":[],"mappings":"AAUA,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACtC,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}
1
+ {"version":3,"file":"advanced.d.ts","sourceRoot":"","sources":["../src/advanced.ts"],"names":[],"mappings":"AAUA,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACtC,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,WAAW,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC"}
package/dist/advanced.js CHANGED
@@ -2,10 +2,10 @@
2
2
  * Copyright (C) 2026 Garudex Labs. All Rights Reserved.
3
3
  * Caracal, a product of Garudex Labs
4
4
  *
5
- * Advanced surface: low-level primitives, codec, ambient context plumbing,
5
+ * Advanced surface: low-level primitives, codec, bound context plumbing,
6
6
  * and the raw coordinator client. Most integrators only need the default
7
7
  * "@caracalai/sdk" entrypoint; reach for these when building a transport
8
- * adapter or a framework shim.
8
+ * adapter or framework integration.
9
9
  */
10
10
  export * from "./envelope.js";
11
11
  export * from "./context.js";
package/dist/client.d.ts CHANGED
@@ -2,15 +2,18 @@ import { type CaracalContext } from "./context.js";
2
2
  import { type HeaderGetter } from "./envelope.js";
3
3
  import { type CoordinatorClient } from "./coordinator.js";
4
4
  import { AgentKind, type DelegationConstraints } from "./coordinator.js";
5
+ import type { JsonObject } from "./json.js";
5
6
  export interface ResourceBinding {
6
7
  resourceId: string;
7
8
  upstreamPrefix: string;
8
9
  }
10
+ export type TokenSource = () => string | Promise<string>;
9
11
  export interface CaracalConfig {
10
12
  coordinator: CoordinatorClient;
11
13
  zoneId: string;
12
14
  applicationId: string;
13
- subjectToken: string;
15
+ subjectToken?: string;
16
+ tokenSource?: TokenSource;
14
17
  gatewayUrl?: string;
15
18
  resources?: ResourceBinding[];
16
19
  defaultKind?: AgentKind;
@@ -19,33 +22,65 @@ export interface CaracalConfig {
19
22
  export interface SpawnOptions {
20
23
  kind?: AgentKind;
21
24
  ttlSeconds?: number;
25
+ subjectSessionId?: string;
22
26
  parentId?: string;
23
- metadata?: Record<string, unknown>;
27
+ metadata?: JsonObject;
24
28
  traceId?: string;
25
29
  }
26
30
  export interface DelegateOptions {
27
31
  to: string;
28
32
  toApplicationId: string;
33
+ resourceId?: string;
29
34
  scopes: string[];
30
35
  constraints?: DelegationConstraints;
31
36
  ttlSeconds?: number;
32
37
  }
33
38
  export interface DelegateToSpawnOptions {
39
+ resourceId?: string;
34
40
  scopes: string[];
35
41
  constraints?: DelegationConstraints;
36
42
  delegationTtlSeconds?: number;
37
43
  kind?: AgentKind;
38
44
  ttlSeconds?: number;
39
- metadata?: Record<string, unknown>;
45
+ metadata?: JsonObject;
40
46
  traceId?: string;
41
47
  }
42
48
  export type LifecycleHook = (ctx: CaracalContext) => void | Promise<void>;
49
+ export interface RootOptions {
50
+ allowRoot?: boolean;
51
+ }
52
+ export interface ClientSecretOptions {
53
+ coordinatorUrl: string;
54
+ stsUrl: string;
55
+ zoneId: string;
56
+ applicationId: string;
57
+ clientSecret: string;
58
+ resources: Array<string | ResourceBinding>;
59
+ gatewayUrl?: string;
60
+ scope?: string;
61
+ fetchImpl?: typeof fetch;
62
+ }
63
+ export interface ConnectOptions {
64
+ env?: NodeJS.ProcessEnv;
65
+ configPath?: string;
66
+ clientSecret?: Partial<ClientSecretOptions>;
67
+ }
68
+ export interface GatewayRequest {
69
+ url: string;
70
+ headers: Record<string, string>;
71
+ }
43
72
  export declare class Caracal {
44
73
  readonly config: CaracalConfig;
45
74
  private agentStartHooks;
46
75
  private agentEndHooks;
47
76
  constructor(config: CaracalConfig);
77
+ /**
78
+ * Builds a Caracal client from explicit values, a generated profile, or env.
79
+ */
80
+ static connect(opts?: ConnectOptions): Caracal;
48
81
  static fromEnv(env?: NodeJS.ProcessEnv): Caracal;
82
+ static fromClientSecret(opts: ClientSecretOptions): Caracal;
83
+ static fromConfig(path?: string, env?: NodeJS.ProcessEnv): Caracal;
49
84
  close(): Promise<void>;
50
85
  spawn<T>(fn: () => Promise<T>, opts?: SpawnOptions): Promise<T>;
51
86
  delegate<T>(opts: DelegateOptions, fn: () => Promise<T>): Promise<T>;
@@ -55,18 +90,33 @@ export declare class Caracal {
55
90
  onAgentEnd(cb: LifecycleHook): void;
56
91
  private fire;
57
92
  current(): CaracalContext | undefined;
58
- headers(): Record<string, string>;
59
- bindFromHeaders<T>(headers: Record<string, string | string[] | undefined> | HeaderGetter, fn: () => Promise<T>): Promise<T>;
93
+ headers(opts?: RootOptions): Record<string, string>;
94
+ headersAsync(opts?: RootOptions): Promise<Record<string, string>>;
95
+ bindFromHeaders<T>(headers: Record<string, string | string[] | undefined> | HeaderGetter, fn: () => Promise<T>, opts?: RootOptions): Promise<T>;
60
96
  /**
61
97
  * Returns a fetch-shaped function that injects the Caracal envelope (traceparent
62
98
  * + baggage) onto outbound requests and, for gateway-routed calls, replaces the
63
99
  * `Authorization` header with the current subject token. Pass to any provider
64
100
  * SDK that accepts a custom fetch.
65
101
  */
66
- transport(): typeof fetch;
102
+ transport(opts?: RootOptions): typeof fetch;
103
+ gatewayRequest(resourceId: string, path?: string): GatewayRequest;
104
+ /**
105
+ * One-call happy path: sends `init` to `path` on the given resource through the
106
+ * Gateway with Caracal context and authority injected. Equivalent to building a
107
+ * `gatewayRequest` and calling it with `transport`. The resource header always
108
+ * wins over any caller-supplied `X-Caracal-Resource`.
109
+ */
110
+ fetch(resourceId: string, path?: string, init?: RequestInit, opts?: RootOptions): Promise<Response>;
67
111
  private routeThroughGateway;
68
- middleware(): (req: {
112
+ /**
113
+ * Binds Caracal context after a verifier boundary. This does not verify JWT
114
+ * signatures, audience, scopes, token use, or revocation.
115
+ */
116
+ contextMiddleware(opts?: RootOptions): (req: {
69
117
  headers: Record<string, string | string[] | undefined>;
70
118
  }, _res: unknown, next: (err?: unknown) => void) => void;
119
+ private rootTokenSync;
120
+ private rootToken;
71
121
  }
72
122
  //# sourceMappingURL=client.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}