@almadar/integrations 2.31.0 → 2.33.0

package/dist/{store-BYRZDq9B.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;
         };
@@ -1845,6 +1857,22 @@ type IntegrationName = keyof IntegrationContracts;
  * ```
  */
 type IntegrationActionName<K extends IntegrationName> = keyof IntegrationContracts[K] & string;
+/**
+ * Every env var name declared anywhere in `serviceCredentials` — provider
+ * secrets and the credential-store's own bootstrap keys alike. The single
+ * source a forked verify/harness process scrubs from its env so it can never
+ * see, and therefore never spend, a real credential (regardless of which
+ * integration mode the fork ends up in).
+ */
+declare function allCredentialEnvVars(): Set<string>;
+/**
+ * Every declared PROVIDER credential env var — `allCredentialEnvVars()` minus
+ * the store's own bootstrap keys. The store-first custody set (I-31):
+ * `RuntimeIntegrationManager` strips these from the base env before merging
+ * the store's decrypted values, so every resolution flows the exact store →
+ * env → unconfigured path a deployed client app uses.
+ */
+declare function declaredCredentialEnvVars(): Set<string>;
 /**
  * Declared side-effect-free "Test connection" probes, executed by the
  * `credentials.test` action through the normal factory path. Only services
@@ -1965,4 +1993,4 @@ declare class CredentialStore {
     remove(envVar: string): Promise<boolean>;
 }
 
-export { type ArxivActions as A, type CLIActions as C, type DatabaseActions as D, type EmailActions as E, type GitHubActions as G, type HookDeclaration as H, type IconifyActions as I, type LLMIntegrationActions as L, type MLActions as M, type OAuthActions as O, type QueueActions as Q, type RedisActions as R, type StorageActions as S, type TwilioActions as T, type WebhookActions as W, type YouTubeActions as Y, CREDENTIAL_ENTITY_TYPE as a, CREDENTIAL_MASTER_KEY_ENV as b, type CredentialEntry as c, type CredentialPersistence as d, CredentialStore as e, type DatabaseDriver as f, type DatabaseQueryParamValue as g, type DatabaseQueryParams as h, type DatabaseQueryResult as i, type DatabaseRow as j, type DeepAgentActions as k, type DockerActions as l, type IntegrationActionName as m, type IntegrationContracts as n, type IntegrationName as o, type OtelActions as p, type StripeActions as q, type WikimediaActions as r, serviceHooks as s };
+export { type ArxivActions as A, type CLIActions as C, type DatabaseActions as D, type EmailActions as E, type GitHubActions as G, type HookDeclaration as H, type IconifyActions as I, type LLMIntegrationActions as L, type MLActions as M, type OAuthActions as O, type QueueActions as Q, type RedisActions as R, type StorageActions as S, type TwilioActions as T, type WebhookActions as W, type YouTubeActions as Y, CREDENTIAL_ENTITY_TYPE as a, CREDENTIAL_MASTER_KEY_ENV as b, type CredentialEntry as c, type CredentialPersistence as d, CredentialStore as e, type DatabaseDriver as f, type DatabaseQueryParamValue as g, type DatabaseQueryParams as h, type DatabaseQueryResult as i, type DatabaseRow as j, type DeepAgentActions as k, type DockerActions as l, type IntegrationActionName as m, type IntegrationContracts as n, type IntegrationName as o, type OtelActions as p, type StripeActions as q, type WikimediaActions as r, allCredentialEnvVars as s, declaredCredentialEnvVars as t, serviceHooks as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/integrations",
-  "version": "2.31.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.81.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",