@almadar/integrations 2.32.0 → 2.33.0

package/dist/{store-C03XILaI.d.ts → store-C5nb44iS.d.ts}

@@ -1,4 +1,4 @@
-import { ServiceParamsValue, ServiceParams, EntityRow } from '@almadar/core';
+import { ServiceParamsValue, ServiceParams, EventPayload, EntityRow } from '@almadar/core';
 import { f as IntegrationParamValue, g as IntegrationParams } from './BaseIntegration-BYlbMFlf.js';
 
 /** Scalar value admissible as a SQL bind parameter. */
@@ -1080,8 +1080,8 @@ type StorageActions = {
             acl?: 'public' | 'private';
             /** Reject the upload if the file-form payload's declared size exceeds this many bytes. */
             maxSize?: number;
-            /** Arbitrary metadata stored alongside the object (in-memory backend only). */
-            metadata?: IntegrationParams;
+            /** Object metadata stored alongside the content (S3-compatible object stores carry metadata as string headers — never structured values). */
+            metadata?: Record<string, string>;
         };
         result: {
             key: string;
@@ -1133,7 +1133,7 @@ type StorageActions = {
             content: string;
             contentType: string;
             size: number;
-            metadata: IntegrationParams;
+            metadata: Record<string, string>;
         };
     };
     /** List object keys in a bucket, optionally prefix-filtered, one page at a time. */
@@ -1189,13 +1189,26 @@ type StorageActions = {
         };
     };
 };
+/** A queued job as stored/returned by the in-memory queue. Extends
+ *  `EventPayload` so it flows through a `ServiceAction.result` (bus-payload-
+ *  shaped) without a boundary cast, the same reason `JsonSchemaDefinition`
+ *  extends `ServiceParams` above. */
+interface QueueJob extends EventPayload {
+    id: string;
+    /** Whatever `enqueue` was given — the caller declares its own shape.
+     *  @shapedBy payload */
+    payload: ServiceParams;
+    enqueuedAt: number;
+    priority: number;
+}
 type QueueActions = {
     /** Add a job to an in-memory job queue, ordered by priority (higher first) among ready jobs. */
     enqueue: {
         params: {
             /** Queue name. */
             queue: string;
-            /** Arbitrary job payload. */
+            /** Job payload — the caller declares its own shape.
+             *  @shapedBy payload */
             payload: ServiceParams;
             /** Delay before the job becomes eligible for dequeue, in milliseconds. */
             delay?: number;
@@ -1214,12 +1227,7 @@ type QueueActions = {
             queue: string;
         };
         result: {
-            job: {
-                id: string;
-                payload: ServiceParams;
-                enqueuedAt: number;
-                priority: number;
-            } | null;
+            job: QueueJob | null;
         };
     };
     /** Look up a job's current status by id. */
@@ -1230,12 +1238,7 @@ type QueueActions = {
         };
         result: {
             status: 'pending' | 'processing' | 'completed' | 'failed';
-            job: {
-                id: string;
-                payload: ServiceParams;
-                enqueuedAt: number;
-                priority: number;
-            } | null;
+            job: QueueJob | null;
         };
     };
     /** Mark a 'processing' job completed and store its result; no-op (returns false) if the job isn't in 'processing' state. */
@@ -1243,7 +1246,8 @@ type QueueActions = {
         params: {
             /** Job id. */
             jobId: string;
-            /** Result payload to attach to the job. */
+            /** Result payload to attach to the job — the caller declares its own shape (not necessarily the same shape as the job's `payload`).
+             *  @shapedBy result */
             result?: ServiceParams;
         };
         result: {
@@ -1293,6 +1297,8 @@ type RedisActions = {
             key: string;
         };
         result: {
+            /** Whatever `set` stored under this key — the caller declares its shape.
+             *  @shapedBy value */
             value: ServiceParams;
         };
     };
@@ -1301,7 +1307,8 @@ type RedisActions = {
         params: {
             /** Cache key. */
             key: string;
-            /** Value to store. */
+            /** Value to store — the caller declares its own shape.
+             *  @shapedBy value */
             value: ServiceParams;
             /** Time-to-live in seconds; omit for no expiry. */
             ttl?: number;
@@ -1374,7 +1381,8 @@ type RedisActions = {
         params: {
             /** Channel name. */
             channel: string;
-            /** Message payload. */
+            /** Message payload — the caller declares its own shape.
+             *  @shapedBy message */
             message: ServiceParams;
         };
         result: {
@@ -1541,8 +1549,8 @@ type OtelActions = {
         params: {
             /** Span name. */
             name: string;
-            /** Key-value attributes attached to the span. */
-            attributes?: IntegrationParams;
+            /** Key-value attributes attached to the span (OTel attribute values are scalar). */
+            attributes?: Record<string, string | number | boolean>;
             /** Existing trace id to attach this span to; a new one is generated when omitted. */
             traceId?: string;
         };
@@ -1570,8 +1578,8 @@ type OtelActions = {
             spanId: string;
             /** Event name. */
             name: string;
-            /** Key-value attributes attached to the event. */
-            attributes?: IntegrationParams;
+            /** Key-value attributes attached to the event (OTel attribute values are scalar). */
+            attributes?: Record<string, string | number | boolean>;
         };
         result: {
             added: boolean;
@@ -1586,8 +1594,8 @@ type OtelActions = {
             value: number;
             /** Aggregation kind; defaults to 'counter'. */
             type?: 'counter' | 'gauge' | 'histogram';
-            /** Key-value labels attached to the metric (replaces prior labels on the same name). */
-            labels?: IntegrationParams;
+            /** Key-value labels attached to the metric (replaces prior labels on the same name; OTel label values are scalar). */
+            labels?: Record<string, string | number | boolean>;
         };
         result: {
             recorded: boolean;
@@ -1646,7 +1654,8 @@ type DeepAgentActions = {
             threadId?: string;
             /** Named skill to invoke for this message. */
             skill?: string;
-            /** Extra context passed through to the agent. */
+            /** Extra context passed through to the agent — the caller declares its own shape.
+             *  @shapedBy context */
             context?: IntegrationParams;
         };
         result: {
@@ -1715,6 +1724,9 @@ type DatabaseActions = {
             params?: DatabaseQueryParamValue[];
         };
         result: {
+            /** One row per matched record, keyed by column name — the shape follows
+             *  the caller's own `sql` SELECT list, which no param's TYPE can express.
+             *  @shapedBy rows */
             rows: DatabaseRow[];
             rowCount: number;
         };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/integrations",
-  "version": "2.32.0",
+  "version": "2.33.0",
   "description": "External service integrations for Almadar applications",
   "type": "module",
   "main": "./dist/index.js",
@@ -33,8 +33,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@almadar/core": "^10.83.0",
-    "@almadar/llm": "^2.48.0",
+    "@almadar/core": "^10.87.0",
+    "@almadar/llm": "^2.49.0",
     "@almadar/logger": "^1.12.0",
     "@aws-sdk/client-s3": "^3.700.0",
     "@aws-sdk/s3-request-presigner": "^3.700.0",
@@ -50,7 +50,7 @@
     "zod": "^3.23.0"
   },
   "devDependencies": {
-    "@almadar/eslint-plugin": "^2.17.0",
+    "@almadar/eslint-plugin": "^2.18.0",
     "@types/node": "^20.0.0",
     "@types/pg": "^8.11.10",
     "@types/web-push": "^3.6.4",