@artinet/sdk 0.5.17 → 0.6.0-preview.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.
- package/README.md +51 -557
- package/dist/browser/browser.d.ts +9 -0
- package/dist/browser/browser.js +10 -0
- package/dist/browser/client/a2a-client.d.ts +127 -0
- package/dist/browser/client/a2a-client.js +233 -0
- package/dist/browser/client/index.d.ts +1 -0
- package/dist/browser/client/index.js +1 -0
- package/dist/browser/config/index.d.ts +158 -0
- package/dist/browser/config/index.js +155 -0
- package/dist/browser/config/observability.d.ts +119 -0
- package/dist/browser/config/observability.js +35 -0
- package/dist/browser/services/a2a/helpers/message-builder.d.ts +17 -0
- package/dist/browser/services/a2a/helpers/message-builder.js +66 -0
- package/dist/browser/transport/rpc/parser.d.ts +15 -0
- package/dist/browser/transport/rpc/parser.js +48 -0
- package/dist/browser/transport/rpc/rpc-client.d.ts +80 -0
- package/dist/browser/transport/rpc/rpc-client.js +189 -0
- package/dist/browser/transport/streaming/event-stream.d.ts +25 -0
- package/dist/browser/transport/streaming/event-stream.js +100 -0
- package/dist/browser/types/a2a/a2a.d.ts +378 -0
- package/dist/browser/types/a2a/a2a.js +14 -0
- package/dist/browser/types/a2a/builder.d.ts +43 -0
- package/dist/browser/types/a2a/index.d.ts +3 -0
- package/dist/browser/types/a2a/index.js +2 -0
- package/dist/{types/interfaces → browser/types}/client.d.ts +25 -27
- package/dist/browser/types/core/core.d.ts +31 -0
- package/dist/browser/types/core/index.d.ts +1 -0
- package/dist/browser/types/core/index.js +1 -0
- package/dist/{types/interfaces/services → browser/types}/index.d.ts +3 -0
- package/dist/{types/interfaces/services → browser/types}/index.js +3 -0
- package/dist/browser/types/mcp/index.d.ts +1 -0
- package/dist/browser/types/mcp/index.js +1 -0
- package/dist/{types/interfaces/services/mcp/service.d.ts → browser/types/mcp/mcp.d.ts} +4 -3
- package/dist/browser/types/mcp/mcp.js +5 -0
- package/dist/browser/types/storage.d.ts +21 -0
- package/dist/browser/types/utils/index.d.ts +1 -0
- package/dist/browser/types/utils/index.js +1 -0
- package/dist/browser/types/utils/transform.d.ts +64 -0
- package/dist/browser/types/utils/transform.js +35 -0
- package/dist/browser/utils/common/constants.d.ts +11 -0
- package/dist/browser/utils/common/constants.js +38 -0
- package/dist/browser/utils/common/errors.d.ts +24 -0
- package/dist/browser/utils/common/errors.js +42 -0
- package/dist/browser/utils/common/utils.d.ts +32 -0
- package/dist/browser/utils/common/utils.js +43 -0
- package/dist/client/a2a-client.d.ts +21 -19
- package/dist/client/a2a-client.js +30 -9
- package/dist/config/default.d.ts +50 -0
- package/dist/config/default.js +62 -0
- package/dist/config/index.d.ts +158 -0
- package/dist/config/index.js +155 -0
- package/dist/config/observability.d.ts +119 -0
- package/dist/config/observability.js +35 -0
- package/dist/extensions/otel.d.ts +98 -0
- package/dist/extensions/otel.js +190 -0
- package/dist/extensions/pino.d.ts +44 -0
- package/dist/extensions/pino.js +107 -0
- package/dist/extensions/winston.d.ts +47 -0
- package/dist/extensions/winston.js +114 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +2 -0
- package/dist/server/express/errors.js +3 -3
- package/dist/server/express/middeware.d.ts +2 -2
- package/dist/server/express/middeware.js +36 -9
- package/dist/server/express/server.d.ts +9 -55
- package/dist/server/express/server.js +51 -32
- package/dist/services/a2a/execute.d.ts +6 -0
- package/dist/services/a2a/execute.js +25 -0
- package/dist/services/a2a/factory/builder.d.ts +21 -80
- package/dist/services/a2a/factory/builder.js +23 -13
- package/dist/services/a2a/factory/context.d.ts +15 -128
- package/dist/services/a2a/factory/context.js +31 -136
- package/dist/services/a2a/factory/handler.d.ts +6 -0
- package/dist/services/a2a/factory/{method.js → handler.js} +2 -2
- package/dist/services/a2a/factory/index.d.ts +1 -2
- package/dist/services/a2a/factory/index.js +1 -2
- package/dist/services/a2a/factory/service.d.ts +20 -7
- package/dist/services/a2a/factory/service.js +4 -4
- package/dist/services/a2a/factory/state-machine.d.ts +11 -0
- package/dist/services/a2a/factory/state-machine.js +66 -0
- package/dist/services/a2a/{state/update → handlers}/artifact.d.ts +4 -4
- package/dist/services/a2a/handlers/cancel-task.d.ts +11 -0
- package/dist/services/a2a/handlers/cancel-task.js +33 -0
- package/dist/services/a2a/handlers/get-task.d.ts +11 -0
- package/dist/services/a2a/handlers/get-task.js +13 -0
- package/dist/services/a2a/handlers/resubscribe-task.d.ts +11 -0
- package/dist/services/a2a/handlers/resubscribe-task.js +56 -0
- package/dist/services/a2a/handlers/send-message.d.ts +11 -0
- package/dist/services/a2a/handlers/send-message.js +35 -0
- package/dist/services/a2a/handlers/stream-message.d.ts +11 -0
- package/dist/services/a2a/handlers/stream-message.js +19 -0
- package/dist/services/a2a/handlers/update.d.ts +17 -0
- package/dist/services/a2a/handlers/update.js +114 -0
- package/dist/services/a2a/helpers/agentcard-builder.d.ts +9 -5
- package/dist/services/a2a/helpers/agentcard-builder.js +5 -0
- package/dist/services/a2a/helpers/content.d.ts +2 -2
- package/dist/services/a2a/helpers/content.js +4 -0
- package/dist/services/a2a/helpers/history.d.ts +6 -0
- package/dist/services/a2a/helpers/history.js +7 -0
- package/dist/services/a2a/helpers/index.d.ts +3 -1
- package/dist/services/a2a/helpers/index.js +3 -1
- package/dist/services/a2a/helpers/message-builder.d.ts +13 -8
- package/dist/services/a2a/helpers/message-builder.js +5 -0
- package/dist/services/a2a/helpers/part.d.ts +9 -9
- package/dist/services/a2a/helpers/references.d.ts +6 -0
- package/dist/services/a2a/helpers/references.js +22 -0
- package/dist/services/a2a/index.d.ts +9 -5
- package/dist/services/a2a/index.js +8 -5
- package/dist/services/a2a/managers.d.ts +23 -0
- package/dist/services/a2a/managers.js +95 -0
- package/dist/services/a2a/messenger.d.ts +35 -0
- package/dist/services/{core/managers/command.js → a2a/messenger.js} +27 -31
- package/dist/services/a2a/service.d.ts +41 -371
- package/dist/services/a2a/service.js +239 -70
- package/dist/services/a2a/state-machine.d.ts +18 -0
- package/dist/services/a2a/state-machine.js +76 -0
- package/dist/services/a2a/streams.d.ts +22 -0
- package/dist/services/a2a/streams.js +98 -0
- package/dist/services/core/index.d.ts +1 -2
- package/dist/services/core/index.js +1 -2
- package/dist/services/core/manager.d.ts +15 -0
- package/dist/services/core/manager.js +42 -0
- package/dist/services/mcp/service.d.ts +11 -15
- package/dist/services/mcp/service.js +16 -16
- package/dist/transport/index.d.ts +0 -1
- package/dist/transport/index.js +1 -1
- package/dist/transport/rpc/parser.d.ts +2 -2
- package/dist/transport/rpc/parser.js +7 -7
- package/dist/transport/rpc/rpc-client.d.ts +5 -5
- package/dist/transport/rpc/rpc-client.js +7 -7
- package/dist/transport/streaming/event-stream.d.ts +3 -3
- package/dist/transport/streaming/event-stream.js +11 -10
- package/dist/transport/trpc/a2a/factory/router.d.ts +479 -871
- package/dist/transport/trpc/a2a/factory/router.js +2 -2
- package/dist/transport/trpc/a2a/routes/info.d.ts +108 -8
- package/dist/transport/trpc/a2a/routes/info.js +6 -2
- package/dist/transport/trpc/a2a/routes/message/route.d.ts +113 -162
- package/dist/transport/trpc/a2a/routes/message/route.js +7 -13
- package/dist/transport/trpc/a2a/routes/tasks/route.d.ts +114 -212
- package/dist/transport/trpc/a2a/routes/tasks/route.js +16 -19
- package/dist/transport/trpc/a2a/trpc.d.ts +9 -253
- package/dist/types/a2a/a2a.d.ts +378 -0
- package/dist/types/a2a/a2a.js +14 -0
- package/dist/types/a2a/builder.d.ts +43 -0
- package/dist/types/a2a/index.d.ts +3 -0
- package/dist/types/a2a/index.js +2 -0
- package/dist/types/client.d.ts +133 -0
- package/dist/types/core/core.d.ts +31 -0
- package/dist/types/core/core.js +1 -0
- package/dist/types/core/index.d.ts +1 -0
- package/dist/types/core/index.js +1 -0
- package/dist/types/index.d.ts +6 -3
- package/dist/types/index.js +6 -3
- package/dist/types/mcp/index.d.ts +1 -0
- package/dist/types/mcp/index.js +1 -0
- package/dist/types/mcp/mcp.d.ts +50 -0
- package/dist/types/mcp/mcp.js +5 -0
- package/dist/types/protocol.d.ts +33 -0
- package/dist/types/protocol.js +34 -0
- package/dist/types/storage.d.ts +21 -0
- package/dist/utils/common/constants.d.ts +7 -7
- package/dist/utils/common/constants.js +10 -10
- package/dist/utils/common/errors.d.ts +18 -17
- package/dist/utils/common/errors.js +14 -13
- package/dist/utils/common/parse.d.ts +7 -0
- package/dist/utils/common/parse.js +14 -0
- package/dist/utils/common/schema-validation.d.ts +2 -0
- package/dist/utils/common/schema-validation.js +12 -0
- package/dist/utils/common/utils.d.ts +23 -0
- package/dist/utils/common/utils.js +32 -0
- package/dist/utils/common/zAsyncIterable-v3.d.ts +1 -1
- package/dist/utils/common/zAsyncIterable-v3.js +2 -1
- package/dist/utils/index.d.ts +3 -3
- package/dist/utils/index.js +3 -3
- package/dist/utils/storage/file.d.ts +8 -17
- package/dist/utils/storage/file.js +44 -73
- package/package.json +86 -23
- package/dist/services/a2a/factory/event.d.ts +0 -58
- package/dist/services/a2a/factory/event.js +0 -177
- package/dist/services/a2a/factory/method.d.ts +0 -6
- package/dist/services/a2a/managers/cancellation.d.ts +0 -11
- package/dist/services/a2a/managers/cancellation.js +0 -16
- package/dist/services/a2a/managers/connection.d.ts +0 -11
- package/dist/services/a2a/managers/connection.js +0 -16
- package/dist/services/a2a/managers/context.d.ts +0 -11
- package/dist/services/a2a/managers/context.js +0 -16
- package/dist/services/a2a/managers/index.d.ts +0 -5
- package/dist/services/a2a/managers/index.js +0 -5
- package/dist/services/a2a/managers/task.d.ts +0 -11
- package/dist/services/a2a/managers/task.js +0 -16
- package/dist/services/a2a/methods/cancel-task.d.ts +0 -7
- package/dist/services/a2a/methods/cancel-task.js +0 -43
- package/dist/services/a2a/methods/get-task.d.ts +0 -112
- package/dist/services/a2a/methods/get-task.js +0 -14
- package/dist/services/a2a/methods/resubscribe-task.d.ts +0 -7
- package/dist/services/a2a/methods/resubscribe-task.js +0 -80
- package/dist/services/a2a/methods/send-message.d.ts +0 -7
- package/dist/services/a2a/methods/send-message.js +0 -19
- package/dist/services/a2a/methods/stream-message.d.ts +0 -8
- package/dist/services/a2a/methods/stream-message.js +0 -21
- package/dist/services/a2a/state/index.d.ts +0 -3
- package/dist/services/a2a/state/index.js +0 -3
- package/dist/services/a2a/state/load.d.ts +0 -14
- package/dist/services/a2a/state/load.js +0 -71
- package/dist/services/a2a/state/process.d.ts +0 -7
- package/dist/services/a2a/state/process.js +0 -13
- package/dist/services/a2a/state/update/index.d.ts +0 -2
- package/dist/services/a2a/state/update/index.js +0 -2
- package/dist/services/a2a/state/update/update.d.ts +0 -23
- package/dist/services/a2a/state/update/update.js +0 -123
- package/dist/services/core/execution/execute.d.ts +0 -6
- package/dist/services/core/execution/execute.js +0 -25
- package/dist/services/core/execution/index.d.ts +0 -1
- package/dist/services/core/execution/index.js +0 -1
- package/dist/services/core/managers/command.d.ts +0 -39
- package/dist/services/core/managers/event.d.ts +0 -18
- package/dist/services/core/managers/event.js +0 -56
- package/dist/services/core/managers/index.d.ts +0 -3
- package/dist/services/core/managers/index.js +0 -3
- package/dist/services/core/managers/stream.d.ts +0 -20
- package/dist/services/core/managers/stream.js +0 -77
- package/dist/types/ext.d.ts +0 -13
- package/dist/types/ext.js +0 -10
- package/dist/types/interfaces/index.d.ts +0 -3
- package/dist/types/interfaces/index.js +0 -3
- package/dist/types/interfaces/services/a2a/builder.d.ts +0 -37
- package/dist/types/interfaces/services/a2a/context.d.ts +0 -162
- package/dist/types/interfaces/services/a2a/engine.d.ts +0 -7
- package/dist/types/interfaces/services/a2a/index.d.ts +0 -5
- package/dist/types/interfaces/services/a2a/index.js +0 -5
- package/dist/types/interfaces/services/a2a/legacy.d.ts +0 -93
- package/dist/types/interfaces/services/a2a/service.d.ts +0 -409
- package/dist/types/interfaces/services/a2a/service.js +0 -5
- package/dist/types/interfaces/services/core/context/command.d.ts +0 -25
- package/dist/types/interfaces/services/core/context/command.js +0 -5
- package/dist/types/interfaces/services/core/context/context.d.ts +0 -207
- package/dist/types/interfaces/services/core/context/context.js +0 -5
- package/dist/types/interfaces/services/core/context/index.d.ts +0 -3
- package/dist/types/interfaces/services/core/context/index.js +0 -3
- package/dist/types/interfaces/services/core/context/types.d.ts +0 -11
- package/dist/types/interfaces/services/core/context/types.js +0 -5
- package/dist/types/interfaces/services/core/execution/engine.d.ts +0 -106
- package/dist/types/interfaces/services/core/execution/engine.js +0 -5
- package/dist/types/interfaces/services/core/execution/environment.d.ts +0 -11
- package/dist/types/interfaces/services/core/execution/environment.js +0 -5
- package/dist/types/interfaces/services/core/execution/execute.d.ts +0 -7
- package/dist/types/interfaces/services/core/execution/execute.js +0 -5
- package/dist/types/interfaces/services/core/execution/index.d.ts +0 -3
- package/dist/types/interfaces/services/core/execution/index.js +0 -3
- package/dist/types/interfaces/services/core/index.d.ts +0 -4
- package/dist/types/interfaces/services/core/index.js +0 -4
- package/dist/types/interfaces/services/core/managers/cancellation.d.ts +0 -9
- package/dist/types/interfaces/services/core/managers/cancellation.js +0 -5
- package/dist/types/interfaces/services/core/managers/connection.d.ts +0 -9
- package/dist/types/interfaces/services/core/managers/connection.js +0 -5
- package/dist/types/interfaces/services/core/managers/context.d.ts +0 -17
- package/dist/types/interfaces/services/core/managers/context.js +0 -5
- package/dist/types/interfaces/services/core/managers/event.d.ts +0 -328
- package/dist/types/interfaces/services/core/managers/event.js +0 -5
- package/dist/types/interfaces/services/core/managers/index.d.ts +0 -6
- package/dist/types/interfaces/services/core/managers/index.js +0 -6
- package/dist/types/interfaces/services/core/managers/stream.d.ts +0 -217
- package/dist/types/interfaces/services/core/managers/stream.js +0 -5
- package/dist/types/interfaces/services/core/managers/task.d.ts +0 -9
- package/dist/types/interfaces/services/core/service.d.ts +0 -115
- package/dist/types/interfaces/services/core/service.js +0 -5
- package/dist/types/interfaces/services/mcp/index.d.ts +0 -1
- package/dist/types/interfaces/services/mcp/index.js +0 -1
- package/dist/types/interfaces/services/mcp/service.js +0 -5
- package/dist/types/interfaces/storage.d.ts +0 -8
- package/dist/types/schemas/a2a/agent.d.ts +0 -2583
- package/dist/types/schemas/a2a/agent.js +0 -323
- package/dist/types/schemas/a2a/auth.d.ts +0 -908
- package/dist/types/schemas/a2a/auth.js +0 -283
- package/dist/types/schemas/a2a/error.d.ts +0 -396
- package/dist/types/schemas/a2a/error.js +0 -163
- package/dist/types/schemas/a2a/index.d.ts +0 -11
- package/dist/types/schemas/a2a/index.js +0 -11
- package/dist/types/schemas/a2a/kind.d.ts +0 -11
- package/dist/types/schemas/a2a/kind.js +0 -20
- package/dist/types/schemas/a2a/message.d.ts +0 -10343
- package/dist/types/schemas/a2a/message.js +0 -130
- package/dist/types/schemas/a2a/notification.d.ts +0 -1517
- package/dist/types/schemas/a2a/notification.js +0 -203
- package/dist/types/schemas/a2a/parameters.d.ts +0 -956
- package/dist/types/schemas/a2a/parameters.js +0 -241
- package/dist/types/schemas/a2a/protocol.d.ts +0 -14363
- package/dist/types/schemas/a2a/protocol.js +0 -59
- package/dist/types/schemas/a2a/rpc.d.ts +0 -182
- package/dist/types/schemas/a2a/rpc.js +0 -126
- package/dist/types/schemas/a2a/task.d.ts +0 -5886
- package/dist/types/schemas/a2a/task.js +0 -134
- package/dist/types/schemas/a2a/transport.d.ts +0 -31
- package/dist/types/schemas/a2a/transport.js +0 -28
- package/dist/types/schemas/index.d.ts +0 -1
- package/dist/types/schemas/index.js +0 -1
- package/dist/utils/logging/index.d.ts +0 -2
- package/dist/utils/logging/index.js +0 -2
- package/dist/utils/logging/log.d.ts +0 -33
- package/dist/utils/logging/log.js +0 -75
- package/dist/utils/logging/logger.d.ts +0 -18
- package/dist/utils/logging/logger.js +0 -18
- package/dist/utils/storage/memory.d.ts +0 -25
- package/dist/utils/storage/memory.js +0 -47
- /package/dist/{types/interfaces/services → browser/types}/a2a/builder.js +0 -0
- /package/dist/{types/interfaces → browser/types}/client.js +0 -0
- /package/dist/{types/interfaces/services/core/managers/task.js → browser/types/core/core.js} +0 -0
- /package/dist/{types/interfaces/services → browser/types}/protocol.d.ts +0 -0
- /package/dist/{types/interfaces/services → browser/types}/protocol.js +0 -0
- /package/dist/{types/interfaces → browser/types}/storage.js +0 -0
- /package/dist/services/a2a/{state/update → handlers}/artifact.js +0 -0
- /package/dist/services/a2a/{methods → handlers}/index.d.ts +0 -0
- /package/dist/services/a2a/{methods → handlers}/index.js +0 -0
- /package/dist/types/{interfaces/services/a2a/context.js → a2a/builder.js} +0 -0
- /package/dist/types/{interfaces/services/a2a/engine.js → client.js} +0 -0
- /package/dist/types/{interfaces/services/a2a/legacy.js → storage.js} +0 -0
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Copyright 2025 The Artinet Project
|
|
3
|
+
* SPDX-License-Identifier: Apache-2.0
|
|
4
|
+
*/
|
|
5
|
+
import { A2A } from "../types/index.js";
|
|
6
|
+
import type { Client } from "../types/client.js";
|
|
7
|
+
/**
|
|
8
|
+
* A2AClient is the main client class for interacting with Agent2Agent (A2A) protocol-compliant services.
|
|
9
|
+
* It provides methods for sending tasks, retrieving statuses, canceling operations, and handling streaming responses.
|
|
10
|
+
*/
|
|
11
|
+
export declare class A2AClient implements Client {
|
|
12
|
+
private baseUrl;
|
|
13
|
+
private cachedAgentCard;
|
|
14
|
+
private customHeaders;
|
|
15
|
+
private fallbackPath;
|
|
16
|
+
private agentUrl;
|
|
17
|
+
private mergePath;
|
|
18
|
+
/**
|
|
19
|
+
* Creates a new A2AClient instance.
|
|
20
|
+
* @param baseUrl The base URL for the A2A server.
|
|
21
|
+
* @param headers Optional custom headers to include in all requests.
|
|
22
|
+
* @param fallbackPath Optional fallback path to use if the agent card is not found at the base URL.
|
|
23
|
+
* @example
|
|
24
|
+
* const client = new A2AClient("http://localhost:4000/a2a");
|
|
25
|
+
* const card = await client.agentCard();
|
|
26
|
+
* console.log(card);
|
|
27
|
+
* @example
|
|
28
|
+
* const client = new A2AClient("http://localhost:4000/a2a", {}, "/agent-card");
|
|
29
|
+
* const card = await client.agentCard();
|
|
30
|
+
* console.log(card);
|
|
31
|
+
*/
|
|
32
|
+
constructor(baseUrl: URL | string, headers?: Record<string, string>, fallbackPath?: string, mergePath?: boolean);
|
|
33
|
+
/**
|
|
34
|
+
* Retrieves the AgentCard from the A2A server.
|
|
35
|
+
* Caches the result after the first successful fetch.
|
|
36
|
+
* @returns A promise resolving to the AgentCard.
|
|
37
|
+
*/
|
|
38
|
+
agentCard(): Promise<A2A.AgentCard>;
|
|
39
|
+
/**
|
|
40
|
+
* Retrieves the AgentCard from the A2A server.
|
|
41
|
+
* @returns A promise resolving to the AgentCard.
|
|
42
|
+
*/
|
|
43
|
+
getAgentCard(): Promise<A2A.AgentCard>;
|
|
44
|
+
/**
|
|
45
|
+
* Refreshes the cached AgentCard by fetching it again from the server.
|
|
46
|
+
* @returns A promise resolving to the updated AgentCard.
|
|
47
|
+
*/
|
|
48
|
+
refreshAgentCard(): Promise<A2A.AgentCard>;
|
|
49
|
+
sendMessage(params: A2A.MessageSendParams): Promise<A2A.Message | A2A.Task | null>;
|
|
50
|
+
sendMessage(params: string | A2A.MessageSendParams["message"]): Promise<A2A.Message | A2A.Task | null>;
|
|
51
|
+
/**
|
|
52
|
+
* @deprecated Use sendMessage instead.
|
|
53
|
+
* Sends a task request to the agent (non-streaming).
|
|
54
|
+
* @param params The parameters for the message/send method.
|
|
55
|
+
* @returns A promise resolving to the Task object or null.
|
|
56
|
+
*/
|
|
57
|
+
sendTask(params: A2A.MessageSendParams): Promise<A2A.Message | A2A.Task | null>;
|
|
58
|
+
/**
|
|
59
|
+
* Sends a Message and returns a stream of status and artifact updates.
|
|
60
|
+
* @param params Task parameters for the request
|
|
61
|
+
* @returns An AsyncIterable that yields TaskStatusUpdateEvent/TaskArtifactUpdateEvent/Task/Message payloads.
|
|
62
|
+
*/
|
|
63
|
+
sendStreamingMessage(params: A2A.MessageSendParams | string): AsyncIterable<A2A.Update>;
|
|
64
|
+
/**
|
|
65
|
+
* @deprecated Use sendStreamingMessage instead.
|
|
66
|
+
* Sends a task and returns a subscription to status and artifact updates.
|
|
67
|
+
* @param params Task parameters for the request
|
|
68
|
+
* @returns An AsyncIterable that yields TaskStatusUpdateEvent or TaskArtifactUpdateEvent payloads.
|
|
69
|
+
*/
|
|
70
|
+
sendTaskSubscribe(params: A2A.MessageSendParams): AsyncIterable<A2A.Update>;
|
|
71
|
+
/**
|
|
72
|
+
* Retrieves the current state of a task.
|
|
73
|
+
* @param params The parameters for the tasks/get method.
|
|
74
|
+
* @returns A promise resolving to the Task object or null.
|
|
75
|
+
*/
|
|
76
|
+
getTask(params: A2A.TaskQueryParams): Promise<A2A.Task | null>;
|
|
77
|
+
/**
|
|
78
|
+
* Cancels a currently running task.
|
|
79
|
+
* @param params The parameters for the tasks/cancel method.
|
|
80
|
+
* @returns A promise resolving to the updated Task object (usually canceled state) or null.
|
|
81
|
+
*/
|
|
82
|
+
cancelTask(params: A2A.TaskIdParams): Promise<A2A.Task | null>;
|
|
83
|
+
/**
|
|
84
|
+
* Sets or updates the push notification config for a task.
|
|
85
|
+
* @param params The parameters for the tasks/pushNotificationConfig/set method (which is TaskPushNotificationConfig).
|
|
86
|
+
* @returns A promise resolving to the confirmed TaskPushNotificationConfig or null.
|
|
87
|
+
*/
|
|
88
|
+
setTaskPushNotification(params: A2A.TaskPushNotificationConfig): Promise<A2A.TaskPushNotificationConfig | null>;
|
|
89
|
+
/**
|
|
90
|
+
* Retrieves the currently configured push notification config for a task.
|
|
91
|
+
* @param params The parameters for the tasks/pushNotificationConfig/get method.
|
|
92
|
+
* @returns A promise resolving to the TaskPushNotificationConfig or null.
|
|
93
|
+
*/
|
|
94
|
+
getTaskPushNotification(params: A2A.TaskIdParams): Promise<A2A.TaskPushNotificationConfig | null>;
|
|
95
|
+
/**
|
|
96
|
+
* Resubscribes to an existing task's update stream.
|
|
97
|
+
* @param params Parameters identifying the task to resubscribe to
|
|
98
|
+
* @returns An AsyncIterable that yields TaskStatusUpdateEvent or TaskArtifactUpdateEvent payloads.
|
|
99
|
+
*/
|
|
100
|
+
resubscribeTask(params: A2A.TaskQueryParams): AsyncIterable<A2A.Update>;
|
|
101
|
+
/**
|
|
102
|
+
* Checks if the server supports a specific capability based on the agent card.
|
|
103
|
+
* @param capability The capability to check (e.g., 'streaming', 'pushNotifications').
|
|
104
|
+
* @returns A promise resolving to true if the capability is supported.
|
|
105
|
+
*/
|
|
106
|
+
supports(capability: "streaming" | "pushNotifications" | "stateTransitionHistory"): Promise<boolean>;
|
|
107
|
+
/**
|
|
108
|
+
* Sets custom headers to be included in all requests.
|
|
109
|
+
* @param headers A record of header name/value pairs.
|
|
110
|
+
*/
|
|
111
|
+
setHeaders(headers: Record<string, string>): void;
|
|
112
|
+
/**
|
|
113
|
+
* Adds a single custom header to be included in all requests.
|
|
114
|
+
* @param name The header name.
|
|
115
|
+
* @param value The header value.
|
|
116
|
+
*/
|
|
117
|
+
addHeader(name: string, value: string): void;
|
|
118
|
+
/**
|
|
119
|
+
* Removes a custom header.
|
|
120
|
+
* @param name The header name to remove.
|
|
121
|
+
*/
|
|
122
|
+
removeHeader(name: string): void;
|
|
123
|
+
/**
|
|
124
|
+
* Clears all custom headers.
|
|
125
|
+
*/
|
|
126
|
+
clearHeaders(): void;
|
|
127
|
+
}
|
|
@@ -0,0 +1,233 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Copyright 2025 The Artinet Project
|
|
3
|
+
* SPDX-License-Identifier: Apache-2.0
|
|
4
|
+
*/
|
|
5
|
+
import { executeJsonRpcRequest, executeGetRequest, } from "../transport/rpc/rpc-client.js";
|
|
6
|
+
import { executeStreamEvents } from "../transport/streaming/event-stream.js";
|
|
7
|
+
import { INTERNAL_ERROR } from "../utils/common/errors.js";
|
|
8
|
+
import { logger } from "../config/index.js";
|
|
9
|
+
import { createMessageSendParams } from "../services/a2a/helpers/message-builder.js";
|
|
10
|
+
/**
|
|
11
|
+
* A2AClient is the main client class for interacting with Agent2Agent (A2A) protocol-compliant services.
|
|
12
|
+
* It provides methods for sending tasks, retrieving statuses, canceling operations, and handling streaming responses.
|
|
13
|
+
*/
|
|
14
|
+
export class A2AClient {
|
|
15
|
+
/**
|
|
16
|
+
* Creates a new A2AClient instance.
|
|
17
|
+
* @param baseUrl The base URL for the A2A server.
|
|
18
|
+
* @param headers Optional custom headers to include in all requests.
|
|
19
|
+
* @param fallbackPath Optional fallback path to use if the agent card is not found at the base URL.
|
|
20
|
+
* @example
|
|
21
|
+
* const client = new A2AClient("http://localhost:4000/a2a");
|
|
22
|
+
* const card = await client.agentCard();
|
|
23
|
+
* console.log(card);
|
|
24
|
+
* @example
|
|
25
|
+
* const client = new A2AClient("http://localhost:4000/a2a", {}, "/agent-card");
|
|
26
|
+
* const card = await client.agentCard();
|
|
27
|
+
* console.log(card);
|
|
28
|
+
*/
|
|
29
|
+
constructor(baseUrl, headers = {}, fallbackPath, mergePath = false) {
|
|
30
|
+
this.cachedAgentCard = null;
|
|
31
|
+
this.customHeaders = {};
|
|
32
|
+
this.baseUrl = typeof baseUrl === "string" ? new URL(baseUrl) : baseUrl;
|
|
33
|
+
this.customHeaders = headers;
|
|
34
|
+
this.fallbackPath = fallbackPath ?? "/agent-card";
|
|
35
|
+
this.agentUrl = this.baseUrl;
|
|
36
|
+
this.mergePath = mergePath;
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* Retrieves the AgentCard from the A2A server.
|
|
40
|
+
* Caches the result after the first successful fetch.
|
|
41
|
+
* @returns A promise resolving to the AgentCard.
|
|
42
|
+
*/
|
|
43
|
+
async agentCard() {
|
|
44
|
+
if (this.cachedAgentCard) {
|
|
45
|
+
return this.cachedAgentCard;
|
|
46
|
+
}
|
|
47
|
+
// Standard location for agent cards
|
|
48
|
+
const wellKnownUrl = new URL("/.well-known/agent-card.json", this.baseUrl);
|
|
49
|
+
if (this.mergePath) {
|
|
50
|
+
wellKnownUrl.pathname = this.baseUrl.pathname + wellKnownUrl.pathname;
|
|
51
|
+
}
|
|
52
|
+
try {
|
|
53
|
+
try {
|
|
54
|
+
if (!URL.canParse(wellKnownUrl)) {
|
|
55
|
+
throw new Error("Invalid well-known URL");
|
|
56
|
+
}
|
|
57
|
+
const card = await executeGetRequest(wellKnownUrl, this.customHeaders, "agent card (well-known)");
|
|
58
|
+
if (!card.name || card.name === null || card.name === undefined) {
|
|
59
|
+
throw new Error("No agent card found");
|
|
60
|
+
}
|
|
61
|
+
this.cachedAgentCard = card;
|
|
62
|
+
}
|
|
63
|
+
catch (error) {
|
|
64
|
+
logger.error("A2AClient:agentCard: Failed to fetch agent card (well-known):", error);
|
|
65
|
+
const fallbackUrl = new URL(this.fallbackPath, this.baseUrl);
|
|
66
|
+
if (this.mergePath) {
|
|
67
|
+
fallbackUrl.pathname = this.baseUrl.pathname + fallbackUrl.pathname;
|
|
68
|
+
}
|
|
69
|
+
const fallbackCard = await executeGetRequest(fallbackUrl, this.customHeaders, "agent card (fallback)");
|
|
70
|
+
if (!fallbackCard.name ||
|
|
71
|
+
fallbackCard.name === null ||
|
|
72
|
+
fallbackCard.name === undefined) {
|
|
73
|
+
throw new Error("No fallback agent card found" + error);
|
|
74
|
+
}
|
|
75
|
+
this.cachedAgentCard = fallbackCard;
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
catch (error) {
|
|
79
|
+
logger.error("A2AClient:agentCard: Failed to fetch or parse agent card:", error);
|
|
80
|
+
throw INTERNAL_ERROR(error);
|
|
81
|
+
}
|
|
82
|
+
this.agentUrl = new URL(this.cachedAgentCard.url, this.baseUrl);
|
|
83
|
+
return this.cachedAgentCard;
|
|
84
|
+
}
|
|
85
|
+
/**
|
|
86
|
+
* Retrieves the AgentCard from the A2A server.
|
|
87
|
+
* @returns A promise resolving to the AgentCard.
|
|
88
|
+
*/
|
|
89
|
+
getAgentCard() {
|
|
90
|
+
return this.agentCard();
|
|
91
|
+
}
|
|
92
|
+
/**
|
|
93
|
+
* Refreshes the cached AgentCard by fetching it again from the server.
|
|
94
|
+
* @returns A promise resolving to the updated AgentCard.
|
|
95
|
+
*/
|
|
96
|
+
async refreshAgentCard() {
|
|
97
|
+
this.cachedAgentCard = null;
|
|
98
|
+
return this.agentCard();
|
|
99
|
+
}
|
|
100
|
+
/**
|
|
101
|
+
* Sends a Message to an agent server.
|
|
102
|
+
* @param params The parameters for the message/send method.
|
|
103
|
+
* @returns A promise resolving to Message/Task response from the agent server or null.
|
|
104
|
+
*/
|
|
105
|
+
async sendMessage(params) {
|
|
106
|
+
return await executeJsonRpcRequest(this.agentUrl, "message/send", typeof params === "string"
|
|
107
|
+
? createMessageSendParams(params)
|
|
108
|
+
: typeof params === "object" && "message" in params
|
|
109
|
+
? params
|
|
110
|
+
: createMessageSendParams({ message: params }), this.customHeaders);
|
|
111
|
+
}
|
|
112
|
+
/**
|
|
113
|
+
* @deprecated Use sendMessage instead.
|
|
114
|
+
* Sends a task request to the agent (non-streaming).
|
|
115
|
+
* @param params The parameters for the message/send method.
|
|
116
|
+
* @returns A promise resolving to the Task object or null.
|
|
117
|
+
*/
|
|
118
|
+
async sendTask(params) {
|
|
119
|
+
return await this.sendMessage(params);
|
|
120
|
+
}
|
|
121
|
+
/**
|
|
122
|
+
* Sends a Message and returns a stream of status and artifact updates.
|
|
123
|
+
* @param params Task parameters for the request
|
|
124
|
+
* @returns An AsyncIterable that yields TaskStatusUpdateEvent/TaskArtifactUpdateEvent/Task/Message payloads.
|
|
125
|
+
*/
|
|
126
|
+
sendStreamingMessage(params) {
|
|
127
|
+
return executeStreamEvents(this.agentUrl, "message/stream", createMessageSendParams(params), this.customHeaders);
|
|
128
|
+
}
|
|
129
|
+
/**
|
|
130
|
+
* @deprecated Use sendStreamingMessage instead.
|
|
131
|
+
* Sends a task and returns a subscription to status and artifact updates.
|
|
132
|
+
* @param params Task parameters for the request
|
|
133
|
+
* @returns An AsyncIterable that yields TaskStatusUpdateEvent or TaskArtifactUpdateEvent payloads.
|
|
134
|
+
*/
|
|
135
|
+
sendTaskSubscribe(params) {
|
|
136
|
+
return this.sendStreamingMessage(params);
|
|
137
|
+
}
|
|
138
|
+
/**
|
|
139
|
+
* Retrieves the current state of a task.
|
|
140
|
+
* @param params The parameters for the tasks/get method.
|
|
141
|
+
* @returns A promise resolving to the Task object or null.
|
|
142
|
+
*/
|
|
143
|
+
async getTask(params) {
|
|
144
|
+
return await executeJsonRpcRequest(this.agentUrl, "tasks/get", params, this.customHeaders);
|
|
145
|
+
}
|
|
146
|
+
/**
|
|
147
|
+
* Cancels a currently running task.
|
|
148
|
+
* @param params The parameters for the tasks/cancel method.
|
|
149
|
+
* @returns A promise resolving to the updated Task object (usually canceled state) or null.
|
|
150
|
+
*/
|
|
151
|
+
async cancelTask(params) {
|
|
152
|
+
return await executeJsonRpcRequest(this.agentUrl, "tasks/cancel", params, this.customHeaders);
|
|
153
|
+
}
|
|
154
|
+
/**
|
|
155
|
+
* Sets or updates the push notification config for a task.
|
|
156
|
+
* @param params The parameters for the tasks/pushNotificationConfig/set method (which is TaskPushNotificationConfig).
|
|
157
|
+
* @returns A promise resolving to the confirmed TaskPushNotificationConfig or null.
|
|
158
|
+
*/
|
|
159
|
+
async setTaskPushNotification(params) {
|
|
160
|
+
return await executeJsonRpcRequest(this.agentUrl, "tasks/pushNotificationConfig/set", params, this.customHeaders);
|
|
161
|
+
}
|
|
162
|
+
/**
|
|
163
|
+
* Retrieves the currently configured push notification config for a task.
|
|
164
|
+
* @param params The parameters for the tasks/pushNotificationConfig/get method.
|
|
165
|
+
* @returns A promise resolving to the TaskPushNotificationConfig or null.
|
|
166
|
+
*/
|
|
167
|
+
async getTaskPushNotification(params) {
|
|
168
|
+
return await executeJsonRpcRequest(this.agentUrl, "tasks/pushNotificationConfig/get", params, this.customHeaders);
|
|
169
|
+
}
|
|
170
|
+
/**
|
|
171
|
+
* Resubscribes to an existing task's update stream.
|
|
172
|
+
* @param params Parameters identifying the task to resubscribe to
|
|
173
|
+
* @returns An AsyncIterable that yields TaskStatusUpdateEvent or TaskArtifactUpdateEvent payloads.
|
|
174
|
+
*/
|
|
175
|
+
resubscribeTask(params) {
|
|
176
|
+
return executeStreamEvents(this.agentUrl, "tasks/resubscribe", params, this.customHeaders);
|
|
177
|
+
}
|
|
178
|
+
/**
|
|
179
|
+
* Checks if the server supports a specific capability based on the agent card.
|
|
180
|
+
* @param capability The capability to check (e.g., 'streaming', 'pushNotifications').
|
|
181
|
+
* @returns A promise resolving to true if the capability is supported.
|
|
182
|
+
*/
|
|
183
|
+
async supports(capability) {
|
|
184
|
+
try {
|
|
185
|
+
const card = await this.agentCard();
|
|
186
|
+
if (!card.capabilities) {
|
|
187
|
+
return false;
|
|
188
|
+
}
|
|
189
|
+
switch (capability) {
|
|
190
|
+
case "streaming":
|
|
191
|
+
return !!card.capabilities.streaming;
|
|
192
|
+
case "pushNotifications":
|
|
193
|
+
return !!card.capabilities.pushNotifications;
|
|
194
|
+
case "stateTransitionHistory":
|
|
195
|
+
return !!card.capabilities.stateTransitionHistory;
|
|
196
|
+
default:
|
|
197
|
+
return false;
|
|
198
|
+
}
|
|
199
|
+
}
|
|
200
|
+
catch (error) {
|
|
201
|
+
logger.error(`A2AClient:supports: Failed to determine support for capability '${capability}':`, error);
|
|
202
|
+
return false; // Assume not supported if card fetch fails
|
|
203
|
+
}
|
|
204
|
+
}
|
|
205
|
+
/**
|
|
206
|
+
* Sets custom headers to be included in all requests.
|
|
207
|
+
* @param headers A record of header name/value pairs.
|
|
208
|
+
*/
|
|
209
|
+
setHeaders(headers) {
|
|
210
|
+
this.customHeaders = { ...headers };
|
|
211
|
+
}
|
|
212
|
+
/**
|
|
213
|
+
* Adds a single custom header to be included in all requests.
|
|
214
|
+
* @param name The header name.
|
|
215
|
+
* @param value The header value.
|
|
216
|
+
*/
|
|
217
|
+
addHeader(name, value) {
|
|
218
|
+
this.customHeaders[name] = value;
|
|
219
|
+
}
|
|
220
|
+
/**
|
|
221
|
+
* Removes a custom header.
|
|
222
|
+
* @param name The header name to remove.
|
|
223
|
+
*/
|
|
224
|
+
removeHeader(name) {
|
|
225
|
+
delete this.customHeaders[name];
|
|
226
|
+
}
|
|
227
|
+
/**
|
|
228
|
+
* Clears all custom headers.
|
|
229
|
+
*/
|
|
230
|
+
clearHeaders() {
|
|
231
|
+
this.customHeaders = {};
|
|
232
|
+
}
|
|
233
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export * from "./a2a-client.js";
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export * from "./a2a-client.js";
|
|
@@ -0,0 +1,158 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview Global configuration for the Artinet runtime.
|
|
3
|
+
*
|
|
4
|
+
* Provides a centralized configuration interface that consumers use to
|
|
5
|
+
* inject their implementations of observability, storage, and other
|
|
6
|
+
* platform-specific dependencies.
|
|
7
|
+
*
|
|
8
|
+
* Design principles:
|
|
9
|
+
* - Single configuration point for the entire SDK
|
|
10
|
+
* - No-op defaults for all optional dependencies
|
|
11
|
+
* - Type-safe configuration interface
|
|
12
|
+
* - Configure once at application startup
|
|
13
|
+
*
|
|
14
|
+
* @module config
|
|
15
|
+
*
|
|
16
|
+
* @example
|
|
17
|
+
* ```typescript
|
|
18
|
+
* import { configure, getLogger, getTracer } from '@artinet/core';
|
|
19
|
+
* import pino from 'pino';
|
|
20
|
+
*
|
|
21
|
+
* // Configure at app startup
|
|
22
|
+
* configure({
|
|
23
|
+
* logger: {
|
|
24
|
+
* debug: (msg, ctx) => pino().debug(ctx, msg),
|
|
25
|
+
* info: (msg, ctx) => pino().info(ctx, msg),
|
|
26
|
+
* warn: (msg, ctx) => pino().warn(ctx, msg),
|
|
27
|
+
* error: (msg, ctx) => pino().error(ctx, msg),
|
|
28
|
+
* },
|
|
29
|
+
* });
|
|
30
|
+
*
|
|
31
|
+
* // Later in your code
|
|
32
|
+
* const logger = getLogger();
|
|
33
|
+
* logger.info('Application started');
|
|
34
|
+
* ```
|
|
35
|
+
*/
|
|
36
|
+
import { ILogger } from "./observability.js";
|
|
37
|
+
import { Tracer } from "@opentelemetry/api";
|
|
38
|
+
/**
|
|
39
|
+
* Artinet SDK configuration interface.
|
|
40
|
+
*
|
|
41
|
+
* All properties are optional - the SDK provides sensible no-op defaults.
|
|
42
|
+
* Configure only what you need.
|
|
43
|
+
*/
|
|
44
|
+
export interface ArtinetConfig {
|
|
45
|
+
/**
|
|
46
|
+
* Logger implementation for structured logging.
|
|
47
|
+
* @default noopLogger (no logging)
|
|
48
|
+
*/
|
|
49
|
+
logger?: ILogger;
|
|
50
|
+
/**
|
|
51
|
+
* Tracer implementation for distributed tracing.
|
|
52
|
+
* @default trace.getTracer('artinet') (no tracing)
|
|
53
|
+
*/
|
|
54
|
+
tracer?: Tracer;
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* Configure the Artinet SDK.
|
|
58
|
+
*
|
|
59
|
+
* Call this once at application startup to inject your implementations.
|
|
60
|
+
* Subsequent calls will merge with existing configuration.
|
|
61
|
+
*
|
|
62
|
+
* @param config - Configuration options
|
|
63
|
+
*
|
|
64
|
+
* @example
|
|
65
|
+
* ```typescript
|
|
66
|
+
* // Basic configuration with console
|
|
67
|
+
* configure({ logger: console });
|
|
68
|
+
* ```
|
|
69
|
+
*
|
|
70
|
+
* @example
|
|
71
|
+
* ```typescript
|
|
72
|
+
* // Production configuration with Pino and OpenTelemetry
|
|
73
|
+
* import pino from 'pino';
|
|
74
|
+
* import { trace } from '@opentelemetry/api';
|
|
75
|
+
*
|
|
76
|
+
* const pinoLogger = pino();
|
|
77
|
+
*
|
|
78
|
+
* configure({
|
|
79
|
+
* logger: {
|
|
80
|
+
* debug: (msg, ...args) => pinoLogger.debug(Object.assign({}, ...args), msg),
|
|
81
|
+
* info: (msg, ...args) => pinoLogger.info(Object.assign({}, ...args), msg),
|
|
82
|
+
* warn: (msg, ...args) => pinoLogger.warn(Object.assign({}, ...args), msg),
|
|
83
|
+
* error: (msg, ...args) => pinoLogger.error(Object.assign({}, ...args), msg),
|
|
84
|
+
* },
|
|
85
|
+
* tracer: {
|
|
86
|
+
* startSpan: (name, attrs) => {
|
|
87
|
+
* const span = trace.getTracer('my-app').startSpan(name);
|
|
88
|
+
* // ... wrap span
|
|
89
|
+
* return wrappedSpan;
|
|
90
|
+
* },
|
|
91
|
+
* },
|
|
92
|
+
* });
|
|
93
|
+
* ```
|
|
94
|
+
*/
|
|
95
|
+
export declare function configure(config: ArtinetConfig): void;
|
|
96
|
+
/**
|
|
97
|
+
* Reset configuration to defaults.
|
|
98
|
+
*
|
|
99
|
+
* Primarily useful for testing to ensure clean state between tests.
|
|
100
|
+
*
|
|
101
|
+
* @example
|
|
102
|
+
* ```typescript
|
|
103
|
+
* beforeEach(() => {
|
|
104
|
+
* resetConfig();
|
|
105
|
+
* });
|
|
106
|
+
* ```
|
|
107
|
+
*/
|
|
108
|
+
export declare function resetConfig(): void;
|
|
109
|
+
/**
|
|
110
|
+
* Get the current configuration.
|
|
111
|
+
*
|
|
112
|
+
* Returns a copy to prevent external mutation.
|
|
113
|
+
*
|
|
114
|
+
* @returns Current configuration (readonly copy)
|
|
115
|
+
*/
|
|
116
|
+
export declare function getConfig(): Readonly<ArtinetConfig>;
|
|
117
|
+
/**
|
|
118
|
+
* Get the configured logger or no-op default.
|
|
119
|
+
*
|
|
120
|
+
* @returns Logger implementation
|
|
121
|
+
*
|
|
122
|
+
* @example
|
|
123
|
+
* ```typescript
|
|
124
|
+
* const logger = getLogger();
|
|
125
|
+
* logger.info('Processing request', { requestId: '123' }, 'extra data');
|
|
126
|
+
* ```
|
|
127
|
+
*/
|
|
128
|
+
export declare function getLogger(): ILogger;
|
|
129
|
+
/**
|
|
130
|
+
* Get the configured tracer or no-op default.
|
|
131
|
+
*
|
|
132
|
+
* @returns Tracer implementation
|
|
133
|
+
*
|
|
134
|
+
* @example
|
|
135
|
+
* ```typescript
|
|
136
|
+
* const tracer = getTracer();
|
|
137
|
+
* const span = tracer.startSpan('processRequest', { requestId: '123' });
|
|
138
|
+
* try {
|
|
139
|
+
* // ... do work
|
|
140
|
+
* span.setStatus('ok');
|
|
141
|
+
* } catch (error) {
|
|
142
|
+
* span.setStatus('error', error.message);
|
|
143
|
+
* throw error;
|
|
144
|
+
* } finally {
|
|
145
|
+
* span.end();
|
|
146
|
+
* }
|
|
147
|
+
* ```
|
|
148
|
+
*/
|
|
149
|
+
export declare function getTracer(): Tracer;
|
|
150
|
+
export declare const logger: {
|
|
151
|
+
debug: (msg: string, ...args: unknown[]) => void;
|
|
152
|
+
info: (msg: string, ...args: unknown[]) => void;
|
|
153
|
+
warn: (msg: string, ...args: unknown[]) => void;
|
|
154
|
+
error: (msg: string, err: unknown) => void;
|
|
155
|
+
setLevel: (level: "debug" | "info" | "warn" | "error") => void | undefined;
|
|
156
|
+
getLevel: () => "error" | "trace" | "verbose" | "debug" | "info" | "warn" | "silent";
|
|
157
|
+
child: (context: Record<string, unknown>) => ILogger;
|
|
158
|
+
};
|
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview Global configuration for the Artinet runtime.
|
|
3
|
+
*
|
|
4
|
+
* Provides a centralized configuration interface that consumers use to
|
|
5
|
+
* inject their implementations of observability, storage, and other
|
|
6
|
+
* platform-specific dependencies.
|
|
7
|
+
*
|
|
8
|
+
* Design principles:
|
|
9
|
+
* - Single configuration point for the entire SDK
|
|
10
|
+
* - No-op defaults for all optional dependencies
|
|
11
|
+
* - Type-safe configuration interface
|
|
12
|
+
* - Configure once at application startup
|
|
13
|
+
*
|
|
14
|
+
* @module config
|
|
15
|
+
*
|
|
16
|
+
* @example
|
|
17
|
+
* ```typescript
|
|
18
|
+
* import { configure, getLogger, getTracer } from '@artinet/core';
|
|
19
|
+
* import pino from 'pino';
|
|
20
|
+
*
|
|
21
|
+
* // Configure at app startup
|
|
22
|
+
* configure({
|
|
23
|
+
* logger: {
|
|
24
|
+
* debug: (msg, ctx) => pino().debug(ctx, msg),
|
|
25
|
+
* info: (msg, ctx) => pino().info(ctx, msg),
|
|
26
|
+
* warn: (msg, ctx) => pino().warn(ctx, msg),
|
|
27
|
+
* error: (msg, ctx) => pino().error(ctx, msg),
|
|
28
|
+
* },
|
|
29
|
+
* });
|
|
30
|
+
*
|
|
31
|
+
* // Later in your code
|
|
32
|
+
* const logger = getLogger();
|
|
33
|
+
* logger.info('Application started');
|
|
34
|
+
* ```
|
|
35
|
+
*/
|
|
36
|
+
import { noopLogger } from "./observability.js";
|
|
37
|
+
import { trace } from "@opentelemetry/api";
|
|
38
|
+
/**
|
|
39
|
+
* Internal configuration state.
|
|
40
|
+
* @internal
|
|
41
|
+
*/
|
|
42
|
+
let _config = {};
|
|
43
|
+
/**
|
|
44
|
+
* Configure the Artinet SDK.
|
|
45
|
+
*
|
|
46
|
+
* Call this once at application startup to inject your implementations.
|
|
47
|
+
* Subsequent calls will merge with existing configuration.
|
|
48
|
+
*
|
|
49
|
+
* @param config - Configuration options
|
|
50
|
+
*
|
|
51
|
+
* @example
|
|
52
|
+
* ```typescript
|
|
53
|
+
* // Basic configuration with console
|
|
54
|
+
* configure({ logger: console });
|
|
55
|
+
* ```
|
|
56
|
+
*
|
|
57
|
+
* @example
|
|
58
|
+
* ```typescript
|
|
59
|
+
* // Production configuration with Pino and OpenTelemetry
|
|
60
|
+
* import pino from 'pino';
|
|
61
|
+
* import { trace } from '@opentelemetry/api';
|
|
62
|
+
*
|
|
63
|
+
* const pinoLogger = pino();
|
|
64
|
+
*
|
|
65
|
+
* configure({
|
|
66
|
+
* logger: {
|
|
67
|
+
* debug: (msg, ...args) => pinoLogger.debug(Object.assign({}, ...args), msg),
|
|
68
|
+
* info: (msg, ...args) => pinoLogger.info(Object.assign({}, ...args), msg),
|
|
69
|
+
* warn: (msg, ...args) => pinoLogger.warn(Object.assign({}, ...args), msg),
|
|
70
|
+
* error: (msg, ...args) => pinoLogger.error(Object.assign({}, ...args), msg),
|
|
71
|
+
* },
|
|
72
|
+
* tracer: {
|
|
73
|
+
* startSpan: (name, attrs) => {
|
|
74
|
+
* const span = trace.getTracer('my-app').startSpan(name);
|
|
75
|
+
* // ... wrap span
|
|
76
|
+
* return wrappedSpan;
|
|
77
|
+
* },
|
|
78
|
+
* },
|
|
79
|
+
* });
|
|
80
|
+
* ```
|
|
81
|
+
*/
|
|
82
|
+
export function configure(config) {
|
|
83
|
+
_config = { ..._config, ...config };
|
|
84
|
+
}
|
|
85
|
+
/**
|
|
86
|
+
* Reset configuration to defaults.
|
|
87
|
+
*
|
|
88
|
+
* Primarily useful for testing to ensure clean state between tests.
|
|
89
|
+
*
|
|
90
|
+
* @example
|
|
91
|
+
* ```typescript
|
|
92
|
+
* beforeEach(() => {
|
|
93
|
+
* resetConfig();
|
|
94
|
+
* });
|
|
95
|
+
* ```
|
|
96
|
+
*/
|
|
97
|
+
export function resetConfig() {
|
|
98
|
+
_config = {};
|
|
99
|
+
}
|
|
100
|
+
/**
|
|
101
|
+
* Get the current configuration.
|
|
102
|
+
*
|
|
103
|
+
* Returns a copy to prevent external mutation.
|
|
104
|
+
*
|
|
105
|
+
* @returns Current configuration (readonly copy)
|
|
106
|
+
*/
|
|
107
|
+
export function getConfig() {
|
|
108
|
+
return { ..._config };
|
|
109
|
+
}
|
|
110
|
+
/**
|
|
111
|
+
* Get the configured logger or no-op default.
|
|
112
|
+
*
|
|
113
|
+
* @returns Logger implementation
|
|
114
|
+
*
|
|
115
|
+
* @example
|
|
116
|
+
* ```typescript
|
|
117
|
+
* const logger = getLogger();
|
|
118
|
+
* logger.info('Processing request', { requestId: '123' }, 'extra data');
|
|
119
|
+
* ```
|
|
120
|
+
*/
|
|
121
|
+
export function getLogger() {
|
|
122
|
+
return _config.logger ?? noopLogger;
|
|
123
|
+
}
|
|
124
|
+
/**
|
|
125
|
+
* Get the configured tracer or no-op default.
|
|
126
|
+
*
|
|
127
|
+
* @returns Tracer implementation
|
|
128
|
+
*
|
|
129
|
+
* @example
|
|
130
|
+
* ```typescript
|
|
131
|
+
* const tracer = getTracer();
|
|
132
|
+
* const span = tracer.startSpan('processRequest', { requestId: '123' });
|
|
133
|
+
* try {
|
|
134
|
+
* // ... do work
|
|
135
|
+
* span.setStatus('ok');
|
|
136
|
+
* } catch (error) {
|
|
137
|
+
* span.setStatus('error', error.message);
|
|
138
|
+
* throw error;
|
|
139
|
+
* } finally {
|
|
140
|
+
* span.end();
|
|
141
|
+
* }
|
|
142
|
+
* ```
|
|
143
|
+
*/
|
|
144
|
+
export function getTracer() {
|
|
145
|
+
return _config.tracer ?? trace.getTracer("artinet");
|
|
146
|
+
}
|
|
147
|
+
export const logger = {
|
|
148
|
+
debug: (msg, ...args) => getLogger()?.debug?.(msg, ...args),
|
|
149
|
+
info: (msg, ...args) => getLogger()?.info?.(msg, ...args),
|
|
150
|
+
warn: (msg, ...args) => getLogger()?.warn?.(msg, ...args),
|
|
151
|
+
error: (msg, err) => getLogger()?.error?.(msg, err),
|
|
152
|
+
setLevel: (level) => getLogger()?.setLevel?.(level),
|
|
153
|
+
getLevel: () => getLogger()?.getLevel?.() ?? "info",
|
|
154
|
+
child: (context) => getLogger()?.child?.(context) ?? noopLogger,
|
|
155
|
+
};
|