@codemation/node-example 0.0.28 → 0.0.30

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @codemation/node-example
 
+## 0.0.30
+
+### Patch Changes
+
+- Updated dependencies [[`a250ab8`](https://github.com/MadeRelevant/codemation/commit/a250ab8b973429cdfe708526a205e2565b004868), [`782e934`](https://github.com/MadeRelevant/codemation/commit/782e93469ea6eee701d976b8f1dc18649d045c79), [`052aba1`](https://github.com/MadeRelevant/codemation/commit/052aba17c9a4faf557bdfaa1a9644a1987ecc25e), [`1a356af`](https://github.com/MadeRelevant/codemation/commit/1a356afae50bd3f982e92c3e9f931e3adbcd131f)]:
+  - @codemation/core@0.8.0
+
+## 0.0.29
+
+### Patch Changes
+
+- Updated dependencies [[`88844f7`](https://github.com/MadeRelevant/codemation/commit/88844f75a48fe051e4cb895c710408855de14da4)]:
+  - @codemation/core@0.7.0
+
 ## 0.0.28
 
 ### Patch Changes

package/dist/index.d.cts

@@ -31,14 +31,106 @@ interface ExponentialRetryPolicySpec {
   readonly jitter?: boolean;
 }
 //#endregion
+//#region ../core/src/contracts/telemetryTypes.d.ts
+type TelemetryAttributePrimitive = string | number | boolean | null;
+interface TelemetryAttributes {
+  readonly [key: string]: TelemetryAttributePrimitive | undefined;
+}
+interface TelemetryMetricRecord {
+  readonly name: string;
+  readonly value: number;
+  readonly unit?: string;
+  readonly attributes?: TelemetryAttributes;
+}
+interface TelemetrySpanEventRecord {
+  readonly name: string;
+  readonly occurredAt?: Date;
+  readonly attributes?: TelemetryAttributes;
+}
+interface TelemetryArtifactAttachment {
+  readonly kind: string;
+  readonly contentType: string;
+  readonly previewText?: string;
+  readonly previewJson?: JsonValue;
+  readonly payloadText?: string;
+  readonly payloadJson?: JsonValue;
+  readonly bytes?: number;
+  readonly truncated?: boolean;
+  readonly expiresAt?: Date;
+}
+interface TelemetryArtifactReference {
+  readonly artifactId: string;
+  readonly traceId?: string;
+  readonly spanId?: string;
+}
+interface TelemetrySpanEnd {
+  readonly status?: "ok" | "error";
+  readonly statusMessage?: string;
+  readonly endedAt?: Date;
+  readonly attributes?: TelemetryAttributes;
+}
+interface TelemetryChildSpanStart {
+  readonly name: string;
+  readonly kind?: "internal" | "client";
+  readonly startedAt?: Date;
+  readonly attributes?: TelemetryAttributes;
+}
+interface TelemetryScope {
+  readonly traceId?: string;
+  readonly spanId?: string;
+  readonly costTracking?: CostTrackingTelemetry;
+  addSpanEvent(args: TelemetrySpanEventRecord): Promise<void> | void;
+  recordMetric(args: TelemetryMetricRecord): Promise<void> | void;
+  attachArtifact(args: TelemetryArtifactAttachment): Promise<TelemetryArtifactReference> | TelemetryArtifactReference;
+}
+interface TelemetrySpanScope extends TelemetryScope {
+  readonly traceId: string;
+  readonly spanId: string;
+  end(args?: TelemetrySpanEnd): Promise<void> | void;
+}
+interface NodeExecutionTelemetry extends ExecutionTelemetry, TelemetrySpanScope {
+  startChildSpan(args: TelemetryChildSpanStart): TelemetrySpanScope;
+}
+interface ExecutionTelemetry extends TelemetryScope {
+  readonly traceId: string;
+  readonly spanId: string;
+  forNode(args: Readonly<{
+    nodeId: NodeId;
+    activationId: NodeActivationId;
+  }>): NodeExecutionTelemetry;
+}
+//#endregion
+//#region ../core/src/contracts/CostTrackingTelemetryContract.d.ts
+type CostTrackingComponent = "chat" | "ocr" | "rag";
+interface CostTrackingUsageRecord {
+  readonly component: CostTrackingComponent;
+  readonly provider: string;
+  readonly operation: string;
+  readonly pricingKey: string;
+  readonly usageUnit: string;
+  readonly quantity: number;
+  readonly modelName?: string;
+  readonly attributes?: TelemetryAttributes;
+}
+interface CostTrackingPriceQuote {
+  readonly currency: string;
+  readonly currencyScale: number;
+  readonly estimatedAmountMinor: number;
+  readonly estimateKind: "catalog";
+}
+interface CostTrackingTelemetry {
+  captureUsage(args: CostTrackingUsageRecord): Promise<CostTrackingPriceQuote | undefined>;
+  forScope(scope: TelemetryScope): CostTrackingTelemetry;
+}
+//#endregion
 //#region ../core/src/contracts/runTypes.d.ts
-
 type NodeInputsByPort = Readonly<Record<InputPortKey, Items>>;
 type NodeExecutionStatus = "pending" | "queued" | "running" | "completed" | "failed" | "skipped";
 interface NodeExecutionError {
   message: string;
   name?: string;
   stack?: string;
+  details?: JsonValue;
 }
 /** Stable id for a single connection invocation row in {@link ConnectionInvocationRecord}. */
 type ConnectionInvocationId = string;
@@ -119,6 +211,7 @@ interface ExecutionContext {
   now: () => Date;
   data: RunDataSnapshot;
   nodeState?: NodeExecutionStatePublisher;
+  telemetry: ExecutionTelemetry;
   binary: ExecutionBinaryService;
   getCredential<TSession = unknown>(slotKey: string): Promise<TSession>;
 }
@@ -126,6 +219,7 @@ interface NodeExecutionContext<TConfig extends NodeConfigBase = NodeConfigBase>
   nodeId: NodeId;
   activationId: NodeActivationId;
   config: TConfig;
+  telemetry: NodeExecutionTelemetry;
   binary: NodeBinaryAttachmentService;
 }
 /**
@@ -158,6 +252,9 @@ interface RunnableNode<TConfig extends RunnableNodeConfig<any, any> = RunnableNo
 //#region ../core/src/contracts/workflowTypes.d.ts
 type WorkflowId = string;
 type NodeId = string;
+type NodeIdRef<TJson = unknown> = NodeId & Readonly<{
+  __codemationNodeJson?: TJson;
+}>;
 type OutputPortKey = string;
 type InputPortKey = string;
 type NodeKind = "trigger" | "node";
@@ -262,8 +359,8 @@ interface ParentExecutionRef {
 }
 interface RunDataSnapshot {
   getOutputs(nodeId: NodeId): NodeOutputs | undefined;
-  getOutputItems(nodeId: NodeId, output?: OutputPortKey): Items;
-  getOutputItem(nodeId: NodeId, itemIndex: number, output?: OutputPortKey): Item | undefined;
+  getOutputItems<TJson = unknown>(nodeId: NodeId | NodeIdRef<TJson>, output?: OutputPortKey): Items<TJson>;
+  getOutputItem<TJson = unknown>(nodeId: NodeId | NodeIdRef<TJson>, itemIndex: number, output?: OutputPortKey): Item<TJson> | undefined;
 }
 interface NodeErrorHandlerArgs<TConfig extends NodeConfigBase = NodeConfigBase> {
   readonly kind: "single" | "multi";

package/dist/index.d.ts

@@ -31,14 +31,106 @@ interface ExponentialRetryPolicySpec {
   readonly jitter?: boolean;
 }
 //#endregion
+//#region ../core/src/contracts/telemetryTypes.d.ts
+type TelemetryAttributePrimitive = string | number | boolean | null;
+interface TelemetryAttributes {
+  readonly [key: string]: TelemetryAttributePrimitive | undefined;
+}
+interface TelemetryMetricRecord {
+  readonly name: string;
+  readonly value: number;
+  readonly unit?: string;
+  readonly attributes?: TelemetryAttributes;
+}
+interface TelemetrySpanEventRecord {
+  readonly name: string;
+  readonly occurredAt?: Date;
+  readonly attributes?: TelemetryAttributes;
+}
+interface TelemetryArtifactAttachment {
+  readonly kind: string;
+  readonly contentType: string;
+  readonly previewText?: string;
+  readonly previewJson?: JsonValue;
+  readonly payloadText?: string;
+  readonly payloadJson?: JsonValue;
+  readonly bytes?: number;
+  readonly truncated?: boolean;
+  readonly expiresAt?: Date;
+}
+interface TelemetryArtifactReference {
+  readonly artifactId: string;
+  readonly traceId?: string;
+  readonly spanId?: string;
+}
+interface TelemetrySpanEnd {
+  readonly status?: "ok" | "error";
+  readonly statusMessage?: string;
+  readonly endedAt?: Date;
+  readonly attributes?: TelemetryAttributes;
+}
+interface TelemetryChildSpanStart {
+  readonly name: string;
+  readonly kind?: "internal" | "client";
+  readonly startedAt?: Date;
+  readonly attributes?: TelemetryAttributes;
+}
+interface TelemetryScope {
+  readonly traceId?: string;
+  readonly spanId?: string;
+  readonly costTracking?: CostTrackingTelemetry;
+  addSpanEvent(args: TelemetrySpanEventRecord): Promise<void> | void;
+  recordMetric(args: TelemetryMetricRecord): Promise<void> | void;
+  attachArtifact(args: TelemetryArtifactAttachment): Promise<TelemetryArtifactReference> | TelemetryArtifactReference;
+}
+interface TelemetrySpanScope extends TelemetryScope {
+  readonly traceId: string;
+  readonly spanId: string;
+  end(args?: TelemetrySpanEnd): Promise<void> | void;
+}
+interface NodeExecutionTelemetry extends ExecutionTelemetry, TelemetrySpanScope {
+  startChildSpan(args: TelemetryChildSpanStart): TelemetrySpanScope;
+}
+interface ExecutionTelemetry extends TelemetryScope {
+  readonly traceId: string;
+  readonly spanId: string;
+  forNode(args: Readonly<{
+    nodeId: NodeId;
+    activationId: NodeActivationId;
+  }>): NodeExecutionTelemetry;
+}
+//#endregion
+//#region ../core/src/contracts/CostTrackingTelemetryContract.d.ts
+type CostTrackingComponent = "chat" | "ocr" | "rag";
+interface CostTrackingUsageRecord {
+  readonly component: CostTrackingComponent;
+  readonly provider: string;
+  readonly operation: string;
+  readonly pricingKey: string;
+  readonly usageUnit: string;
+  readonly quantity: number;
+  readonly modelName?: string;
+  readonly attributes?: TelemetryAttributes;
+}
+interface CostTrackingPriceQuote {
+  readonly currency: string;
+  readonly currencyScale: number;
+  readonly estimatedAmountMinor: number;
+  readonly estimateKind: "catalog";
+}
+interface CostTrackingTelemetry {
+  captureUsage(args: CostTrackingUsageRecord): Promise<CostTrackingPriceQuote | undefined>;
+  forScope(scope: TelemetryScope): CostTrackingTelemetry;
+}
+//#endregion
 //#region ../core/src/contracts/runTypes.d.ts
-
 type NodeInputsByPort = Readonly<Record<InputPortKey, Items>>;
 type NodeExecutionStatus = "pending" | "queued" | "running" | "completed" | "failed" | "skipped";
 interface NodeExecutionError {
   message: string;
   name?: string;
   stack?: string;
+  details?: JsonValue;
 }
 /** Stable id for a single connection invocation row in {@link ConnectionInvocationRecord}. */
 type ConnectionInvocationId = string;
@@ -119,6 +211,7 @@ interface ExecutionContext {
   now: () => Date;
   data: RunDataSnapshot;
   nodeState?: NodeExecutionStatePublisher;
+  telemetry: ExecutionTelemetry;
   binary: ExecutionBinaryService;
   getCredential<TSession = unknown>(slotKey: string): Promise<TSession>;
 }
@@ -126,6 +219,7 @@ interface NodeExecutionContext<TConfig extends NodeConfigBase = NodeConfigBase>
   nodeId: NodeId;
   activationId: NodeActivationId;
   config: TConfig;
+  telemetry: NodeExecutionTelemetry;
   binary: NodeBinaryAttachmentService;
 }
 /**
@@ -158,6 +252,9 @@ interface RunnableNode<TConfig extends RunnableNodeConfig<any, any> = RunnableNo
 //#region ../core/src/contracts/workflowTypes.d.ts
 type WorkflowId = string;
 type NodeId = string;
+type NodeIdRef<TJson = unknown> = NodeId & Readonly<{
+  __codemationNodeJson?: TJson;
+}>;
 type OutputPortKey = string;
 type InputPortKey = string;
 type NodeKind = "trigger" | "node";
@@ -262,8 +359,8 @@ interface ParentExecutionRef {
 }
 interface RunDataSnapshot {
   getOutputs(nodeId: NodeId): NodeOutputs | undefined;
-  getOutputItems(nodeId: NodeId, output?: OutputPortKey): Items;
-  getOutputItem(nodeId: NodeId, itemIndex: number, output?: OutputPortKey): Item | undefined;
+  getOutputItems<TJson = unknown>(nodeId: NodeId | NodeIdRef<TJson>, output?: OutputPortKey): Items<TJson>;
+  getOutputItem<TJson = unknown>(nodeId: NodeId | NodeIdRef<TJson>, itemIndex: number, output?: OutputPortKey): Item<TJson> | undefined;
 }
 interface NodeErrorHandlerArgs<TConfig extends NodeConfigBase = NodeConfigBase> {
   readonly kind: "single" | "multi";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemation/node-example",
-  "version": "0.0.28",
+  "version": "0.0.30",
   "publishConfig": {
     "access": "public"
   },
@@ -28,7 +28,7 @@
     }
   },
   "dependencies": {
-    "@codemation/core": "0.6.0"
+    "@codemation/core": "0.8.0"
   },
   "devDependencies": {
     "@types/node": "^25.3.5",