@carbon-js/sdk 0.0.1

package/dist/core/tools/wrap-tool.mjs

@@ -0,0 +1,120 @@
+import { buildToolEvent, createErrorStatus, createOkStatus } from "../utils/build-events.mjs";
+import { createSdkInstrumentation } from "../utils/instrumentation.mjs";
+import { isPromiseLike } from "../../utils/promise.mjs";
+import { stringify } from "../../utils/stringify.mjs";
+function createWrappedTool(args) {
+  return (...callArgs) => {
+    const parsedArgs = parseToolCallArgs({ args: callArgs });
+    const startTimeMs = Date.now();
+    try {
+      const result = args.run(...parsedArgs.toolArgs);
+      if (isPromiseLike({ value: result })) {
+        return Promise.resolve(result).then(
+          (resolvedResult) => {
+            captureToolResult({
+              args: parsedArgs.toolArgs,
+              carbon: parsedArgs.carbon,
+              name: args.name,
+              result: resolvedResult,
+              startTimeMs,
+              captureToolCall: args.captureToolCall
+            });
+            return resolvedResult;
+          },
+          (error) => {
+            captureToolResult({
+              args: parsedArgs.toolArgs,
+              carbon: parsedArgs.carbon,
+              name: args.name,
+              result: getToolErrorResult({ error }),
+              startTimeMs,
+              status: createErrorStatus({ error }),
+              captureToolCall: args.captureToolCall
+            });
+            throw error;
+          }
+        );
+      }
+      captureToolResult({
+        args: parsedArgs.toolArgs,
+        carbon: parsedArgs.carbon,
+        name: args.name,
+        result,
+        startTimeMs,
+        captureToolCall: args.captureToolCall
+      });
+      return result;
+    } catch (error) {
+      captureToolResult({
+        args: parsedArgs.toolArgs,
+        carbon: parsedArgs.carbon,
+        name: args.name,
+        result: getToolErrorResult({ error }),
+        startTimeMs,
+        status: createErrorStatus({ error }),
+        captureToolCall: args.captureToolCall
+      });
+      throw error;
+    }
+  };
+}
+function parseToolCallArgs(args) {
+  const lastArg = args.args.at(-1);
+  const options = getToolCallOptions({ value: lastArg });
+  if (options) {
+    return {
+      carbon: options,
+      toolArgs: args.args.slice(0, -1)
+    };
+  }
+  return {
+    toolArgs: args.args
+  };
+}
+function getToolCallOptions(args) {
+  if (!args.value || typeof args.value !== "object") {
+    return null;
+  }
+  const keys = Object.keys(args.value);
+  if (!keys.some((key) => key === "context" || key === "additionalProperties" || key === "traceId")) {
+    return null;
+  }
+  return args.value;
+}
+function captureToolResult(args) {
+  args.captureToolCall({
+    event: buildToolEvent({
+      context: args.carbon?.context,
+      additionalProperties: args.carbon?.additionalProperties,
+      endTimeMs: Date.now(),
+      instrumentation: createSdkInstrumentation({
+        sourceFunction: "wrapTool",
+        sourcePackage: "ai",
+        sourceProvider: "vercel"
+      }),
+      startTimeMs: args.startTimeMs,
+      status: args.status ?? createOkStatus(),
+      traceId: args.carbon?.traceId,
+      tool: {
+        args: stringify({ value: serializeToolArgs({ args: args.args }) }),
+        name: args.name,
+        result: stringify({ value: args.result })
+      }
+    })
+  });
+}
+function serializeToolArgs(args) {
+  if (args.args.length === 1) {
+    return args.args[0];
+  }
+  return args.args;
+}
+function getToolErrorResult(args) {
+  if (args.error instanceof Error) {
+    return args.error.message;
+  }
+  return args.error;
+}
+export {
+  createWrappedTool
+};

package/dist/core/transport/file-transport.d.mts

@@ -0,0 +1,16 @@
+import { T_EventTransport, T_EventBatch } from './types.mjs';
+import '../../internal/schema/events.mjs';
+import 'zod';
+
+type T_FileTransport = {
+    dirPath?: string;
+};
+declare class FileTransport implements T_EventTransport {
+    private readonly dirPath;
+    constructor(args?: T_FileTransport);
+    sendBatch(args: {
+        batch: T_EventBatch;
+    }): Promise<void>;
+}
+
+export { FileTransport };

package/dist/core/transport/file-transport.mjs

@@ -0,0 +1,17 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { generateId } from "../../utils/ids.mjs";
+class FileTransport {
+  dirPath;
+  constructor(args = {}) {
+    this.dirPath = args.dirPath ?? join(process.cwd(), ".tmp");
+  }
+  async sendBatch(args) {
+    const outputPath = join(this.dirPath, Date.now().toString() + "-" + generateId() + ".json");
+    mkdirSync(dirname(outputPath), { recursive: true });
+    writeFileSync(outputPath, JSON.stringify(args.batch, null, 2));
+  }
+}
+export {
+  FileTransport
+};

package/dist/core/transport/http-transport.d.mts

@@ -0,0 +1,31 @@
+import { T_EventTransport, T_EventBatch } from './types.mjs';
+import '../../internal/schema/events.mjs';
+import 'zod';
+
+type T_HttpTransport = {
+    apiKey?: string;
+    baseUrl?: string;
+    retryMaxAttempts?: number;
+    retryMaxElapsedMs?: number;
+    timeoutMs?: number;
+};
+declare class CarbonIngestError extends Error {
+    readonly retryable: boolean;
+    readonly status: number;
+    constructor(args: {
+        status: number;
+    });
+}
+declare class HttpTransport implements T_EventTransport {
+    private readonly apiKey;
+    private readonly retryMaxAttempts;
+    private readonly retryMaxElapsedMs;
+    private readonly timeoutMs;
+    private readonly url;
+    constructor(args: T_HttpTransport);
+    sendBatch(args: {
+        batch: T_EventBatch;
+    }): Promise<void>;
+}
+
+export { CarbonIngestError, HttpTransport };

package/dist/core/transport/http-transport.mjs

@@ -0,0 +1,79 @@
+import { CONSTANTS } from "../../lib/constants.mjs";
+import { retry } from "../../utils/retry.mjs";
+import { runWithTimeout } from "../../utils/timeout.mjs";
+class CarbonIngestError extends Error {
+  retryable;
+  status;
+  constructor(args) {
+    super(`Carbon ingest failed with status ${args.status}`);
+    this.name = "CarbonIngestError";
+    this.status = args.status;
+    this.retryable = [408, 409, 425, 429].includes(args.status) || args.status >= 500;
+  }
+}
+class HttpTransport {
+  apiKey;
+  retryMaxAttempts;
+  retryMaxElapsedMs;
+  timeoutMs;
+  url;
+  constructor(args) {
+    this.apiKey = getApiKey({ apiKey: args.apiKey });
+    this.retryMaxAttempts = validatePositiveInteger({
+      name: "retryMaxAttempts",
+      value: args.retryMaxAttempts ?? CONSTANTS.api.retryMaxAttempts
+    });
+    this.retryMaxElapsedMs = validatePositiveInteger({
+      name: "retryMaxElapsedMs",
+      value: args.retryMaxElapsedMs ?? CONSTANTS.api.retryMaxElapsedMs
+    });
+    this.timeoutMs = validatePositiveInteger({
+      name: "timeoutMs",
+      value: args.timeoutMs ?? CONSTANTS.api.timeoutMs
+    });
+    this.url = (args.baseUrl ?? CONSTANTS.api.baseUrl).trim().replace(/\/+$/, "") + CONSTANTS.api.ingestPath;
+  }
+  async sendBatch(args) {
+    await retry({
+      maxAttempts: this.retryMaxAttempts,
+      maxElapsedMs: this.retryMaxElapsedMs,
+      run: async () => {
+        await runWithTimeout({
+          timeoutMs: this.timeoutMs,
+          run: async ({ signal }) => {
+            const response = await fetch(this.url, {
+              method: "POST",
+              headers: {
+                authorization: `Bearer ${this.apiKey}`,
+                "content-type": "application/json"
+              },
+              body: JSON.stringify(args.batch),
+              signal
+            });
+            if (!response.ok) {
+              throw new CarbonIngestError({ status: response.status });
+            }
+          }
+        });
+      },
+      shouldRetry: ({ error }) => !(error instanceof CarbonIngestError) || error.retryable
+    });
+  }
+}
+function getApiKey(args) {
+  const apiKey = args.apiKey ?? process.env.CARBON_API_KEY;
+  if (!apiKey) {
+    throw new Error("CARBON_API_KEY is required when using the HTTP transport.");
+  }
+  return apiKey;
+}
+function validatePositiveInteger(args) {
+  if (!Number.isInteger(args.value) || args.value <= 0) {
+    throw new Error(`${args.name} must be a positive integer.`);
+  }
+  return args.value;
+}
+export {
+  CarbonIngestError,
+  HttpTransport
+};

package/dist/core/transport/memory-transport.d.mts

@@ -0,0 +1,12 @@
+import { T_EventTransport, T_EventBatch } from './types.mjs';
+import '../../internal/schema/events.mjs';
+import 'zod';
+
+declare class MemoryTransport implements T_EventTransport {
+    readonly batches: T_EventBatch[];
+    sendBatch(args: {
+        batch: T_EventBatch;
+    }): Promise<void>;
+}
+
+export { MemoryTransport };

package/dist/core/transport/memory-transport.mjs

@@ -0,0 +1,11 @@
+class MemoryTransport {
+  batches = [];
+  async sendBatch(args) {
+    this.batches.push({
+      events: [...args.batch.events]
+    });
+  }
+}
+export {
+  MemoryTransport
+};

package/dist/core/transport/types.d.mts

@@ -0,0 +1,13 @@
+import { a as T_Event } from '../../internal/schema/events.mjs';
+import 'zod';
+
+type T_EventTransport = {
+    sendBatch: (args: {
+        batch: T_EventBatch;
+    }) => Promise<void>;
+};
+type T_EventBatch = {
+    events: T_Event[];
+};
+
+export type { T_EventBatch, T_EventTransport };

package/dist/core/utils/build-events.d.mts

@@ -0,0 +1,33 @@
+import { c as T_EventAiUsage, d as T_EventAdditionalProperties, e as T_EventContext, f as T_EventBase, T as T_LLMEvent, g as T_EventStatus, b as T_ToolEvent } from '../../internal/schema/events.mjs';
+import 'zod';
+
+type T_EventContextInput = Partial<Record<keyof T_EventContext, string>>;
+type T_EventPropertiesInput = {
+    additionalProperties?: T_EventAdditionalProperties;
+    context?: T_EventContextInput;
+};
+declare const EMPTY_AI_USAGE: T_EventAiUsage;
+declare const createOkStatus: () => T_EventStatus;
+declare const createErrorStatus: (args: {
+    error: unknown;
+}) => T_EventStatus;
+declare function buildLlmEvent(args: T_EventPropertiesInput & {
+    endTimeMs: number;
+    id?: string;
+    instrumentation?: T_EventBase["instrumentation"];
+    llm: T_LLMEvent["properties"]["llm"];
+    startTimeMs: number;
+    status: T_EventStatus;
+    traceId?: string;
+}): T_LLMEvent;
+declare function buildToolEvent(args: T_EventPropertiesInput & {
+    endTimeMs: number;
+    id?: string;
+    instrumentation?: T_EventBase["instrumentation"];
+    startTimeMs: number;
+    status: T_EventStatus;
+    tool: T_ToolEvent["properties"]["tool"];
+    traceId?: string;
+}): T_ToolEvent;
+
+export { EMPTY_AI_USAGE, buildLlmEvent, buildToolEvent, createErrorStatus, createOkStatus };

package/dist/core/utils/build-events.mjs

@@ -0,0 +1,132 @@
+import { generateId } from "../../utils/ids.mjs";
+import { createSdkInstrumentation } from "./instrumentation.mjs";
+import { Z_Event } from "../../internal/schema/index.mjs";
+const EMPTY_AI_USAGE = {
+  inputTokenDetails: {
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
+    uncachedTokens: 0
+  },
+  inputTokens: 0,
+  outputTokenDetails: {
+    reasoningTokens: 0,
+    responseTokens: 0
+  },
+  outputTokens: 0,
+  totalTokens: 0
+};
+const createOkStatus = () => {
+  return {
+    state: "ok"
+  };
+};
+const createErrorStatus = (args) => {
+  const message = args.error instanceof Error ? args.error.message : String(args.error);
+  return {
+    error: {
+      ...getErrorCode({ error: args.error }) ? { code: getErrorCode({ error: args.error }) } : {},
+      ...getHttpStatus({ error: args.error }) ? { httpStatus: getHttpStatus({ error: args.error }) } : {},
+      message
+    },
+    state: "error"
+  };
+};
+function buildLlmEvent(args) {
+  const event = {
+    ...buildBaseEvent({
+      additionalProperties: args.additionalProperties,
+      context: args.context,
+      endTimeMs: args.endTimeMs,
+      id: args.id,
+      instrumentation: args.instrumentation,
+      startTimeMs: args.startTimeMs,
+      status: args.status,
+      traceId: args.traceId,
+      type: "llm"
+    }),
+    properties: {
+      llm: args.llm
+    },
+    type: "llm"
+  };
+  return Z_Event.parse(event);
+}
+function buildToolEvent(args) {
+  const event = {
+    ...buildBaseEvent({
+      additionalProperties: args.additionalProperties,
+      context: args.context,
+      endTimeMs: args.endTimeMs,
+      id: args.id,
+      instrumentation: args.instrumentation,
+      startTimeMs: args.startTimeMs,
+      status: args.status,
+      traceId: args.traceId,
+      type: "tool"
+    }),
+    properties: {
+      tool: args.tool
+    },
+    type: "tool"
+  };
+  return Z_Event.parse(event);
+}
+function buildBaseEvent(args) {
+  return {
+    additionalProperties: args.additionalProperties ?? {},
+    context: buildEventContext({ context: args.context }),
+    durationMs: Math.max(args.endTimeMs - args.startTimeMs, 0),
+    endTimeMs: args.endTimeMs,
+    id: args.id ?? generateId(),
+    instrumentation: args.instrumentation ?? createSdkInstrumentation({
+      sourceFunction: "manual",
+      sourcePackage: "ai",
+      sourceProvider: "vercel"
+    }),
+    startTimeMs: args.startTimeMs,
+    status: args.status,
+    ...args.traceId ? { traceId: args.traceId } : {},
+    type: args.type
+  };
+}
+function buildEventContext(args) {
+  return {
+    ...args.context?.agentId ? { agentId: args.context.agentId } : {},
+    ...args.context?.agentGroupId ? { agentGroupId: args.context.agentGroupId } : {},
+    ...args.context?.threadId ? { threadId: args.context.threadId } : {},
+    ...args.context?.userId ? { userId: args.context.userId } : {}
+  };
+}
+function getErrorCode(args) {
+  const error = asRecord({ value: args.error });
+  if (typeof error?.code === "string") {
+    return error.code;
+  }
+  if (typeof error?.type === "string") {
+    return error.type;
+  }
+  if (args.error instanceof Error) {
+    return args.error.name;
+  }
+  return void 0;
+}
+function getHttpStatus(args) {
+  const error = asRecord({ value: args.error });
+  if (typeof error?.status === "number") {
+    return error.status;
+  }
+  if (typeof error?.statusCode === "number") {
+    return error.statusCode;
+  }
+  return void 0;
+}
+function asRecord(args) {
+  return typeof args.value === "object" && args.value !== null ? args.value : null;
+}
+export {
+  EMPTY_AI_USAGE,
+  buildLlmEvent,
+  buildToolEvent,
+  createErrorStatus,
+  createOkStatus
+};

package/dist/core/utils/instrumentation.d.mts

@@ -0,0 +1,12 @@
+import { f as T_EventBase } from '../../internal/schema/events.mjs';
+import 'zod';
+
+type T_SourceProvider = T_EventBase["instrumentation"]["sourceProvider"];
+type T_SourcePackage = T_EventBase["instrumentation"]["sourcePackage"];
+declare function createSdkInstrumentation(args: {
+    sourceFunction?: string;
+    sourcePackage: T_SourcePackage;
+    sourceProvider: T_SourceProvider;
+}): T_EventBase["instrumentation"];
+
+export { createSdkInstrumentation };

package/dist/core/utils/instrumentation.mjs

@@ -0,0 +1,12 @@
+function createSdkInstrumentation(args) {
+  return {
+    provider: "carbon",
+    providerPackage: "sdk",
+    sourceFunction: args.sourceFunction,
+    sourcePackage: args.sourcePackage,
+    sourceProvider: args.sourceProvider
+  };
+}
+export {
+  createSdkInstrumentation
+};

package/dist/index.d.mts

@@ -0,0 +1,10 @@
+export { Carbon, T_CarbonOptions } from './core/carbon.mjs';
+export { T_CarbonContext, T_CarbonObject } from './core/schema/carbon-object.mjs';
+export { FileTransport } from './core/transport/file-transport.mjs';
+export { CarbonIngestError, HttpTransport } from './core/transport/http-transport.mjs';
+export { MemoryTransport } from './core/transport/memory-transport.mjs';
+export { T_EventBatch, T_EventTransport } from './core/transport/types.mjs';
+export { T_WrapToolArgs } from './core/tools/wrap-tool.mjs';
+import './core/runtime.mjs';
+import './internal/schema/events.mjs';
+import 'zod';

package/dist/index.mjs

@@ -0,0 +1,11 @@
+import { Carbon } from "./core/carbon.mjs";
+import { FileTransport } from "./core/transport/file-transport.mjs";
+import { HttpTransport, CarbonIngestError } from "./core/transport/http-transport.mjs";
+import { MemoryTransport } from "./core/transport/memory-transport.mjs";
+export {
+  Carbon,
+  CarbonIngestError,
+  FileTransport,
+  HttpTransport,
+  MemoryTransport
+};