@averta-security/sdk-core 0.1.0-beta.0 → 0.1.0-beta.1

package/README.md

@@ -40,8 +40,7 @@ The public surface includes:
 import { AvertaDecisionClient } from "@averta-security/sdk-core";
 
 const client = new AvertaDecisionClient({
-  avertaApiKey: process.env.AVERTA_API_KEY!,
-  sdk: {
+  clientMetadata: {
     name: "custom-adapter",
     version: "0.1.0",
   },
@@ -50,11 +49,11 @@ const client = new AvertaDecisionClient({
 
 Options:
 
-- `avertaApiKey`: required Averta API key.
+- `avertaApiKey`: optional Averta API key. Defaults to `process.env.AVERTA_API_KEY`.
 - `avertaBaseUrl`: optional Averta API base URL. Defaults to `https://api.averta.io`.
 - `decisionTimeoutMs`: optional decision request timeout in milliseconds. Defaults to `30000`. Set to `0` to disable the SDK-managed timeout.
 - `fetch`: optional custom `fetch` implementation.
-- `sdk`: adapter name and version metadata sent to Averta.
+- `clientMetadata`: adapter name and version metadata. `sdk-core` sends this over the wire as `client: { type: "sdk", ...clientMetadata }`.
 
 ## Errors
 

package/dist/decision-client.d.ts

@@ -1,12 +1,12 @@
 import type { DecisionClientOptions, DecisionPreflightInput, OutputDecisionInput, DecisionResponse, ToolCallDecisionInput, ToolResultDecisionInput } from "./types.ts";
 export declare class AvertaDecisionClient {
     private readonly avertaBaseUrl;
+    private readonly clientMetadata;
     private readonly decisionTimeoutMs;
     private readonly fetchImpl;
-    private readonly sdk;
     constructor(options: DecisionClientOptions);
     private readonly avertaApiKey;
-    preflight(input: Omit<DecisionPreflightInput, "sdk">): Promise<DecisionResponse>;
+    preflight(input: DecisionPreflightInput): Promise<DecisionResponse>;
     checkToolCall(input: ToolCallDecisionInput): Promise<DecisionResponse>;
     checkToolResult(input: ToolResultDecisionInput): Promise<DecisionResponse>;
     checkOutput(input: OutputDecisionInput): Promise<DecisionResponse>;

package/dist/decision-client.js

@@ -1,4 +1,5 @@
 import { AvertaSdkError } from "./errors.js";
+import { resolveAvertaApiKey } from "./env.js";
 import { ensureRequestContext } from "./ids.js";
 import { isObject } from "./values.js";
 const DEFAULT_AVERTA_BASE_URL = "https://api.averta.io";
@@ -155,6 +156,18 @@ function toToolsPayload(tools) {
         type: tool.type,
     }));
 }
+function toMediaPayload(media) {
+    if (!media) {
+        return undefined;
+    }
+    return media.map((item) => ({
+        data_base64: item.dataBase64,
+        ...(item.filename ? { filename: item.filename } : {}),
+        ...(item.id ? { id: item.id } : {}),
+        kind: item.kind,
+        mime_type: item.mimeType,
+    }));
+}
 function toToolCallPayload(toolCall) {
     return {
         ...(toolCall.arguments && toolCall.arguments.value !== undefined
@@ -204,6 +217,7 @@ function toToolCallContextPayload(context) {
 function toCheckpointPayload(input) {
     if (input.checkpointType === "request") {
         return {
+            ...(input.media ? { media: toMediaPayload(input.media) } : {}),
             payload: input.payload,
             ...(input.tools ? { tools: toToolsPayload(input.tools) } : {}),
         };
@@ -299,20 +313,21 @@ function createDecisionAbortState(input) {
 }
 export class AvertaDecisionClient {
     avertaBaseUrl;
+    clientMetadata;
     decisionTimeoutMs;
     fetchImpl;
-    sdk;
     constructor(options) {
         this.avertaBaseUrl = options.avertaBaseUrl ?? DEFAULT_AVERTA_BASE_URL;
+        this.clientMetadata = options.clientMetadata;
         this.decisionTimeoutMs = normalizeDecisionTimeoutMs(options.decisionTimeoutMs);
         this.fetchImpl = options.fetch ?? fetch;
-        this.sdk = options.sdk;
-        this.avertaApiKey = options.avertaApiKey;
+        this.avertaApiKey = resolveAvertaApiKey(options.avertaApiKey);
     }
     avertaApiKey;
     async preflight(input) {
         const response = await this.sendDecisionRequest({
             checkpointType: "request",
+            ...(input.media ? { media: input.media } : {}),
             provider: input.provider,
             payload: input.payload,
             ...(input.tools ? { tools: input.tools } : {}),
@@ -416,7 +431,10 @@ export class AvertaDecisionClient {
                     ...(abortState.signal ? { signal: abortState.signal } : {}),
                     body: JSON.stringify({
                         checkpoint_type: input.checkpointType,
-                        sdk: this.sdk,
+                        client: {
+                            type: "sdk",
+                            ...this.clientMetadata,
+                        },
                         provider: toProviderPayload(input.provider),
                         ...toCheckpointPayload(input),
                         request_context: toRequestContextPayload(ensureRequestContext(input.requestContext)),

package/dist/env.d.ts

@@ -0,0 +1,2 @@
+export declare function readAvertaApiKeyFromEnv(): string | undefined;
+export declare function resolveAvertaApiKey(avertaApiKey?: string): string;

package/dist/env.js

@@ -0,0 +1,14 @@
+import { AvertaSdkError } from "./errors.js";
+export function readAvertaApiKeyFromEnv() {
+    const value = globalThis.process?.env?.AVERTA_API_KEY;
+    const trimmed = typeof value === "string" ? value.trim() : "";
+    return trimmed || undefined;
+}
+export function resolveAvertaApiKey(avertaApiKey) {
+    const explicit = typeof avertaApiKey === "string" ? avertaApiKey.trim() : "";
+    const resolved = explicit || readAvertaApiKeyFromEnv();
+    if (!resolved) {
+        throw new AvertaSdkError("Averta API key is required. Pass avertaApiKey or set AVERTA_API_KEY.", "missing_averta_api_key");
+    }
+    return resolved;
+}

package/dist/guard-flow.d.ts

@@ -1,7 +1,8 @@
 import { AvertaSdkError } from "./errors.ts";
-import type { AvertaProviderMetadata, AvertaRequestContext, DecisionPayload, DecisionResponse, NormalizedToolDefinition, OutputDecisionInput, ToolCallContext, ToolCallDecisionInput, ToolCallDecisionCandidate, ToolResultDecisionInput } from "./types.ts";
+import type { AvertaProviderMetadata, AvertaRequestContext, DecisionMediaItem, DecisionPayload, DecisionResponse, NormalizedToolDefinition, OutputDecisionInput, ToolCallContext, ToolCallDecisionInput, ToolCallDecisionCandidate, ToolResultDecisionInput } from "./types.ts";
 type DecisionClientWithPreflight = {
     preflight(input: {
+        media?: DecisionMediaItem[];
         provider: AvertaProviderMetadata;
         payload: DecisionPayload;
         requestContext?: AvertaRequestContext;
@@ -46,6 +47,7 @@ export declare function prepareGuardedRequest<TTool>(input: {
     decisionClient: DecisionClientWithPreflight & DecisionClientWithToolResultDecision;
     filterTools: (tools: readonly TTool[] | undefined, blockedTools: readonly string[] | undefined) => TTool[] | undefined;
     getPreflightInput: () => {
+        media?: DecisionMediaItem[];
         payload: DecisionPayload;
         tools?: NormalizedToolDefinition[];
     };

package/dist/guard-flow.js

@@ -91,6 +91,7 @@ export async function prepareGuardedRequest(input) {
     else {
         const preflightInput = input.getPreflightInput();
         const decision = await input.decisionClient.preflight({
+            media: preflightInput.media,
             provider: input.provider,
             payload: preflightInput.payload,
             requestContext: input.requestContext,

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { AvertaDecisionClient } from "./decision-client.ts";
+export { readAvertaApiKeyFromEnv, resolveAvertaApiKey } from "./env.ts";
 export { AvertaSdkError } from "./errors.ts";
 export { createRequestId, createTraceId, ensureRequestContext } from "./ids.ts";
 export { filterToolsByIdentity } from "./filter-tools.ts";
@@ -8,4 +9,4 @@ export { buildForwardedToolInput, omitProviderFields } from "./provider-input.ts
 export { StreamingOutputGuard } from "./streaming-output-guard.ts";
 export { isObject, readTrimmedString } from "./values.ts";
 export type { AvertaSdkErrorOptions, } from "./errors.ts";
-export type { AvertaProviderMetadata, AvertaRequestContext, AvertaSdkMetadata, DecisionClientOptions, DecisionPayload, DecisionPreflightInput, DecisionReason, DecisionResponse, DecisionRewriteAction, NormalizedToolDefinition, OutputDecisionInput, PreparedAvertaRequestContext, ToolCallContext, ToolCallContextMessage, ToolCallDecisionCandidate, ToolCallDecisionInput, ToolResultDecisionInput, } from "./types.ts";
+export type { AvertaClientMetadata, AvertaProviderMetadata, AvertaRequestContext, DecisionMediaItem, DecisionClientOptions, DecisionPayload, DecisionPreflightInput, DecisionReason, DecisionResponse, DecisionRewriteAction, NormalizedToolDefinition, OutputDecisionInput, PreparedAvertaRequestContext, ToolCallContext, ToolCallContextMessage, ToolCallDecisionCandidate, ToolCallDecisionInput, ToolResultDecisionInput, } from "./types.ts";

package/dist/index.js

@@ -1,4 +1,5 @@
 export { AvertaDecisionClient } from "./decision-client.js";
+export { readAvertaApiKeyFromEnv, resolveAvertaApiKey } from "./env.js";
 export { AvertaSdkError } from "./errors.js";
 export { createRequestId, createTraceId, ensureRequestContext } from "./ids.js";
 export { filterToolsByIdentity } from "./filter-tools.js";

package/dist/types.d.ts

@@ -7,7 +7,7 @@ export type PreparedAvertaRequestContext = AvertaRequestContext & {
     requestId: string;
     traceId: string;
 };
-export type AvertaSdkMetadata = {
+export type AvertaClientMetadata = {
     name: string;
     version: string;
 };
@@ -26,8 +26,15 @@ export type NormalizedToolDefinition = {
 export type DecisionPayload = {
     text: string;
 };
+export type DecisionMediaItem = {
+    dataBase64: string;
+    filename?: string;
+    id?: string;
+    kind: "image";
+    mimeType: "image/jpeg" | "image/png" | "image/webp";
+};
 export type DecisionPreflightInput = {
-    sdk: AvertaSdkMetadata;
+    media?: DecisionMediaItem[];
     provider: AvertaProviderMetadata;
     payload: unknown;
     signal?: AbortSignal;
@@ -119,7 +126,7 @@ export type DecisionResponse = {
     };
 };
 export type DecisionClientOptions = {
-    avertaApiKey: string;
+    avertaApiKey?: string;
     avertaBaseUrl?: string;
     /**
      * Maximum time to wait for an Averta decision request. Defaults to 30000.
@@ -127,5 +134,5 @@ export type DecisionClientOptions = {
      */
     decisionTimeoutMs?: number;
     fetch?: typeof fetch;
-    sdk: AvertaSdkMetadata;
+    clientMetadata: AvertaClientMetadata;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@averta-security/sdk-core",
-  "version": "0.1.0-beta.0",
+  "version": "0.1.0-beta.1",
   "description": "Shared Averta SDK decision-plane runtime primitives.",
   "license": "SEE LICENSE IN LICENSE.md",
   "type": "module",