@stackables/bridge-graphql 0.0.1 → 1.0.1

package/build/{bridge-transform.d.ts → bridge-graphql/src/bridge-transform.d.ts}

@@ -1,12 +1,20 @@
 import { type GraphQLSchema } from "graphql";
 import { type Logger, type ToolTrace, type TraceLevel } from "@stackables/bridge-core";
-import type { Instruction, ToolMap } from "@stackables/bridge-core";
+import type { BridgeDocument, ToolMap } from "@stackables/bridge-core";
 export type { Logger };
 export type BridgeOptions = {
-    /** Tool functions available to the engine.
-     *  Supports namespaced nesting: `{ myNamespace: { myTool } }`.
-     *  The built-in `std` namespace and `httpCall` are always included;
-     *  user tools are merged on top (shallow). */
+    /**
+     * Tool functions available to the engine.
+     * Supports namespaced nesting: `{ myNamespace: { myTool } }`.
+     * The built-in `std` namespace is always included; user tools are
+     * merged on top (shallow).
+     *
+     * To provide a specific version of std (e.g. when bridge files
+     * target an older major), use a versioned namespace key:
+     * ```ts
+     * tools: { "std@1.5": oldStdNamespace }
+     * ```
+     */
     tools?: ToolMap;
     /** Optional function to reshape/restrict the GQL context before it reaches bridge files.
      *  By default the full context is exposed via `with context`. */
@@ -24,9 +32,9 @@ export type BridgeOptions = {
      */
     logger?: Logger;
 };
-/** Instructions can be a static array or a function that selects per-request */
-export type InstructionSource = Instruction[] | ((context: any) => Instruction[]);
-export declare function bridgeTransform(schema: GraphQLSchema, instructions: InstructionSource, options?: BridgeOptions): GraphQLSchema;
+/** Document can be a static BridgeDocument or a function that selects per-request */
+export type DocumentSource = BridgeDocument | ((context: any) => BridgeDocument);
+export declare function bridgeTransform(schema: GraphQLSchema, document: DocumentSource, options?: BridgeOptions): GraphQLSchema;
 /**
  * Read traces that were collected during the current request.
  * Pass the GraphQL context object; returns an empty array when tracing is

package/build/bridge-graphql/src/bridge-transform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge-transform.d.ts","sourceRoot":"","sources":["../../../src/bridge-transform.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,aAAa,EAEnB,MAAM,SAAS,CAAC;AACjB,OAAO,EAKL,KAAK,MAAM,EACX,KAAK,SAAS,EACd,KAAK,UAAU,EAChB,MAAM,yBAAyB,CAAC;AAKjC,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAGvE,YAAY,EAAE,MAAM,EAAE,CAAC;AAUvB,MAAM,MAAM,aAAa,GAAG;IAC1B;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;qEACiE;IACjE,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,KAAK,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACtD;;;6DAGyD;IACzD,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,qFAAqF;AACrF,MAAM,MAAM,cAAc,GACtB,cAAc,GACd,CAAC,CAAC,OAAO,EAAE,GAAG,KAAK,cAAc,CAAC,CAAC;AAEvC,wBAAgB,eAAe,CAC7B,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,cAAc,EACxB,OAAO,CAAC,EAAE,aAAa,GACtB,aAAa,CAmIf;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,GAAG,GAAG,SAAS,EAAE,CAEzD;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB;wBAER;QAAE,IAAI,EAAE;YAAE,YAAY,EAAE,GAAG,CAAA;SAAE,CAAA;KAAE;8CAK5C;YACD,MAAM,EAAE,GAAG,CAAC;YACZ,SAAS,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,IAAI,CAAC;SAC7B;;EAeR"}

package/build/{bridge-transform.js → bridge-graphql/src/bridge-transform.js}

@@ -1,7 +1,7 @@
 import { MapperKind, mapSchema } from "@graphql-tools/utils";
 import { GraphQLList, GraphQLNonNull, defaultFieldResolver, } from "graphql";
-import { ExecutionTree, TraceCollector, } from "@stackables/bridge-core";
-import { std } from "@stackables/bridge-stdlib";
+import { ExecutionTree, TraceCollector, resolveStd, checkHandleVersions, } from "@stackables/bridge-core";
+import { std as bundledStd, STD_VERSION as BUNDLED_STD_VERSION, } from "@stackables/bridge-stdlib";
 import { SELF_MODULE } from "@stackables/bridge-core";
 const noop = () => { };
 const defaultLogger = {
@@ -10,8 +10,8 @@ const defaultLogger = {
     warn: noop,
     error: noop,
 };
-export function bridgeTransform(schema, instructions, options) {
-    const userTools = options?.tools;
+export function bridgeTransform(schema, document, options) {
+    const userTools = options?.tools ?? {};
     const contextMapper = options?.contextMapper;
     const traceLevel = options?.trace ?? "off";
     const logger = options?.logger ?? defaultLogger;
@@ -33,13 +33,21 @@ export function bridgeTransform(schema, instructions, options) {
                 resolve: async function (source, args, context, info) {
                     // Start execution tree at query/mutation root
                     if (!source && !info.path.prev) {
-                        const activeInstructions = typeof instructions === "function"
-                            ? instructions(context)
-                            : instructions;
+                        const activeDoc = typeof document === "function" ? document(context) : document;
+                        // Resolve which std to use: bundled, or a versioned namespace from tools
+                        const { namespace: activeStd, version: activeStdVersion } = resolveStd(activeDoc.version, bundledStd, BUNDLED_STD_VERSION, userTools);
+                        // std is always included; user tools merge on top (shallow)
+                        // internal tools are injected automatically by ExecutionTree
+                        const allTools = {
+                            std: activeStd,
+                            ...userTools,
+                        };
+                        // Verify all @version-tagged handles can be satisfied
+                        checkHandleVersions(activeDoc.instructions, allTools, activeStdVersion);
                         // Only intercept fields that have a matching bridge instruction.
                         // Fields without one fall through to their original resolver,
                         // allowing hand-coded resolvers to coexist with bridge-powered ones.
-                        const hasBridge = activeInstructions.some((i) => i.kind === "bridge" &&
+                        const hasBridge = activeDoc.instructions.some((i) => i.kind === "bridge" &&
                             i.type === typeName &&
                             i.field === fieldName);
                         if (!hasBridge) {
@@ -48,13 +56,7 @@ export function bridgeTransform(schema, instructions, options) {
                         const bridgeContext = contextMapper
                             ? contextMapper(context)
                             : (context ?? {});
-                        // std is always included; user tools merge on top (shallow)
-                        // internal tools are injected automatically by ExecutionTree
-                        const allTools = {
-                            std,
-                            ...(userTools ?? {}),
-                        };
-                        source = new ExecutionTree(trunk, activeInstructions, allTools, bridgeContext);
+                        source = new ExecutionTree(trunk, activeDoc, allTools, bridgeContext);
                         source.logger = logger;
                         if (traceLevel !== "off") {
                             source.tracer = new TraceCollector(traceLevel);

package/build/{index.d.ts → bridge-graphql/src/index.d.ts}

@@ -7,5 +7,5 @@
  * Peer dependencies: `graphql`, `@graphql-tools/utils`.
  */
 export { bridgeTransform, getBridgeTraces, useBridgeTracing, } from "./bridge-transform.ts";
-export type { BridgeOptions, InstructionSource } from "./bridge-transform.ts";
+export type { BridgeOptions, DocumentSource } from "./bridge-transform.ts";
 //# sourceMappingURL=index.d.ts.map

package/build/bridge-graphql/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,eAAe,EACf,eAAe,EACf,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC"}

package/build/bridge-stdlib/src/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @stackables/bridge-stdlib — Bridge standard library tools.
+ *
+ * Contains the `std` namespace tools (httpCall, string helpers, array helpers,
+ * audit) that ship with Bridge.  Referenced in `.bridge` files as
+ * `std.httpCall`, `std.str.toUpperCase`, etc.
+ *
+ * Separated from core so it can be versioned independently.
+ */
+import { audit } from "./tools/audit.ts";
+import * as arrays from "./tools/arrays.ts";
+import * as strings from "./tools/strings.ts";
+/**
+ * Standard library version.
+ *
+ * The bridge `version X.Y` header declares the minimum compatible std version.
+ * At runtime the engine compares this constant against the bridge's declared
+ * version to verify compatibility (same major, equal-or-higher minor).
+ */
+export declare const STD_VERSION = "1.5.0";
+export declare const std: {
+    readonly str: typeof strings;
+    readonly arr: typeof arrays;
+    readonly audit: typeof audit;
+    readonly httpCall: import("@stackables/bridge-types").ToolCallFn;
+};
+/**
+ * All known built-in tool names as "namespace.tool" strings.
+ *
+ * Useful for LSP/IDE autocomplete and diagnostics.
+ */
+export declare const builtinToolNames: readonly string[];
+export { createHttpCall } from "./tools/http-call.ts";
+//# sourceMappingURL=index.d.ts.map

package/build/bridge-stdlib/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../bridge-stdlib/src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAEzC,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC;AAC5C,OAAO,KAAK,OAAO,MAAM,oBAAoB,CAAC;AAE9C;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,UAAU,CAAC;AASnC,eAAO,MAAM,GAAG;;;;;CAKN,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,MAAM,EAE7C,CAAC;AAEF,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC"}

package/build/bridge-stdlib/src/index.js

@@ -0,0 +1,40 @@
+/**
+ * @stackables/bridge-stdlib — Bridge standard library tools.
+ *
+ * Contains the `std` namespace tools (httpCall, string helpers, array helpers,
+ * audit) that ship with Bridge.  Referenced in `.bridge` files as
+ * `std.httpCall`, `std.str.toUpperCase`, etc.
+ *
+ * Separated from core so it can be versioned independently.
+ */
+import { audit } from "./tools/audit.js";
+import { createHttpCall } from "./tools/http-call.js";
+import * as arrays from "./tools/arrays.js";
+import * as strings from "./tools/strings.js";
+/**
+ * Standard library version.
+ *
+ * The bridge `version X.Y` header declares the minimum compatible std version.
+ * At runtime the engine compares this constant against the bridge's declared
+ * version to verify compatibility (same major, equal-or-higher minor).
+ */
+export const STD_VERSION = "1.5.0";
+/**
+ * Standard built-in tools — available under the `std` namespace.
+ *
+ * Referenced in `.bridge` files as `std.str.toUpperCase`, `std.arr.first`, etc.
+ */
+const httpCallFn = createHttpCall();
+export const std = {
+    str: strings,
+    arr: arrays,
+    audit,
+    httpCall: httpCallFn,
+};
+/**
+ * All known built-in tool names as "namespace.tool" strings.
+ *
+ * Useful for LSP/IDE autocomplete and diagnostics.
+ */
+export const builtinToolNames = Object.keys(std).map((k) => `std.${k}`);
+export { createHttpCall } from "./tools/http-call.js";

package/build/bridge-stdlib/src/tools/arrays.d.ts

@@ -0,0 +1,28 @@
+export declare function filter(opts: {
+    in: any[];
+    [key: string]: any;
+}): any[];
+export declare function find(opts: {
+    in: any[];
+    [key: string]: any;
+}): any;
+/**
+ * Returns the first element of the array in `opts.in`.
+ *
+ * By default silently returns `undefined` for empty arrays.
+ * Set `opts.strict` to `true` (or the string "true") to throw when
+ * the array is empty or contains more than one element.
+ */
+export declare function first(opts: {
+    in: any[];
+    strict?: boolean | string;
+}): any;
+/**
+ * Wraps a single value in an array.
+ *
+ * If `opts.in` is already an array it is returned as-is.
+ */
+export declare function toArray(opts: {
+    in: any;
+}): any[];
+//# sourceMappingURL=arrays.d.ts.map

package/build/bridge-stdlib/src/tools/arrays.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arrays.d.ts","sourceRoot":"","sources":["../../../../../bridge-stdlib/src/tools/arrays.ts"],"names":[],"mappings":"AAAA,wBAAgB,MAAM,CAAC,IAAI,EAAE;IAAE,EAAE,EAAE,GAAG,EAAE,CAAC;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;CAAE,SAU7D;AAED,wBAAgB,IAAI,CAAC,IAAI,EAAE;IAAE,EAAE,EAAE,GAAG,EAAE,CAAC;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;CAAE,OAU3D;AAED;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE;IAAE,EAAE,EAAE,GAAG,EAAE,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,GAAG,MAAM,CAAA;CAAE,OAgBnE;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE;IAAE,EAAE,EAAE,GAAG,CAAA;CAAE,SAExC"}

package/build/bridge-stdlib/src/tools/arrays.js

@@ -0,0 +1,50 @@
+export function filter(opts) {
+    const { in: arr, ...criteria } = opts;
+    return arr.filter((obj) => {
+        for (const [key, value] of Object.entries(criteria)) {
+            if (obj[key] !== value) {
+                return false;
+            }
+        }
+        return true;
+    });
+}
+export function find(opts) {
+    const { in: arr, ...criteria } = opts;
+    return arr.find((obj) => {
+        for (const [key, value] of Object.entries(criteria)) {
+            if (obj[key] !== value) {
+                return false;
+            }
+        }
+        return true;
+    });
+}
+/**
+ * Returns the first element of the array in `opts.in`.
+ *
+ * By default silently returns `undefined` for empty arrays.
+ * Set `opts.strict` to `true` (or the string "true") to throw when
+ * the array is empty or contains more than one element.
+ */
+export function first(opts) {
+    const arr = opts.in;
+    const strict = opts.strict === true || opts.strict === "true";
+    if (strict) {
+        if (!Array.isArray(arr) || arr.length === 0) {
+            throw new Error("pickFirst: expected a non-empty array");
+        }
+        if (arr.length > 1) {
+            throw new Error(`pickFirst: expected exactly one element but got ${arr.length}`);
+        }
+    }
+    return Array.isArray(arr) ? arr[0] : undefined;
+}
+/**
+ * Wraps a single value in an array.
+ *
+ * If `opts.in` is already an array it is returned as-is.
+ */
+export function toArray(opts) {
+    return Array.isArray(opts.in) ? opts.in : [opts.in];
+}

package/build/bridge-stdlib/src/tools/audit.d.ts

@@ -0,0 +1,36 @@
+import type { ToolContext } from "@stackables/bridge-types";
+/**
+ * Built-in audit tool — logs all inputs via the engine logger.
+ *
+ * Designed for use with `force` — wire any number of inputs,
+ * force the handle, and every key-value pair is logged.
+ *
+ * The logger comes from the engine's `ToolContext` (configured via
+ * `BridgeOptions.logger`).  When no logger is configured the engine's
+ * default no-op logger applies — nothing is logged.
+ *
+ * Structured logging style: data object first, message tag last.
+ *
+ * The log level defaults to `info` but can be overridden via `level` input:
+ * ```bridge
+ * audit.level = "warn"
+ * ```
+ *
+ * ```bridge
+ * bridge Mutation.createOrder {
+ *   with std.audit as audit
+ *   with orderApi as api
+ *   with input as i
+ *   with output as o
+ *
+ *   api.userId <- i.userId
+ *   audit.action = "createOrder"
+ *   audit.userId <- i.userId
+ *   audit.orderId <- api.id
+ *   force audit
+ *   o.id <- api.id
+ * }
+ * ```
+ */
+export declare function audit(input: Record<string, any>, context?: ToolContext): Record<string, any>;
+//# sourceMappingURL=audit.d.ts.map

package/build/bridge-stdlib/src/tools/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../../../../bridge-stdlib/src/tools/audit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,CAAC,EAAE,WAAW,uBAKtE"}

package/build/bridge-stdlib/src/tools/audit.js

@@ -0,0 +1,39 @@
+/**
+ * Built-in audit tool — logs all inputs via the engine logger.
+ *
+ * Designed for use with `force` — wire any number of inputs,
+ * force the handle, and every key-value pair is logged.
+ *
+ * The logger comes from the engine's `ToolContext` (configured via
+ * `BridgeOptions.logger`).  When no logger is configured the engine's
+ * default no-op logger applies — nothing is logged.
+ *
+ * Structured logging style: data object first, message tag last.
+ *
+ * The log level defaults to `info` but can be overridden via `level` input:
+ * ```bridge
+ * audit.level = "warn"
+ * ```
+ *
+ * ```bridge
+ * bridge Mutation.createOrder {
+ *   with std.audit as audit
+ *   with orderApi as api
+ *   with input as i
+ *   with output as o
+ *
+ *   api.userId <- i.userId
+ *   audit.action = "createOrder"
+ *   audit.userId <- i.userId
+ *   audit.orderId <- api.id
+ *   force audit
+ *   o.id <- api.id
+ * }
+ * ```
+ */
+export function audit(input, context) {
+    const { level = "info", ...data } = input;
+    const log = context?.logger?.[level];
+    log?.(data, "[bridge:audit]");
+    return input;
+}

package/build/bridge-stdlib/src/tools/http-call.d.ts

@@ -0,0 +1,35 @@
+import type { CacheStore, ToolCallFn } from "@stackables/bridge-types";
+/**
+ * Parse TTL (in seconds) from HTTP response headers.
+ *
+ * Priority: `Cache-Control: s-maxage` > `Cache-Control: max-age` > `Expires`.
+ * Returns 0 if the response is uncacheable (no-store, no-cache, or no headers).
+ */
+declare function parseCacheTTL(response: Response): number;
+/**
+ * Create an httpCall tool function — the built-in REST API tool.
+ *
+ * Receives a fully-built input object from the engine and makes an HTTP call.
+ * The engine resolves all wires (from tool definition + bridge wires) before calling.
+ *
+ * Expected input shape:
+ *   { baseUrl, method?, path?, headers?, cache?, ...shorthandFields }
+ *
+ * Routing rules:
+ *   - GET: shorthand fields → query string parameters
+ *   - POST/PUT/PATCH/DELETE: shorthand fields → JSON body
+ *   - `headers` object passed as HTTP headers
+ *   - `baseUrl` + `path` concatenated for the URL
+ *
+ * Cache modes:
+ *   - `cache = "auto"` (default) — respect HTTP Cache-Control / Expires headers
+ *   - `cache = 0` — disable caching entirely
+ *   - `cache = <seconds>` — explicit TTL override, ignores response headers
+ *
+ * @param fetchFn - Fetch implementation (override for testing)
+ * @param cacheStore - Pluggable cache store (default: in-memory LRU, 1024 entries)
+ */
+export declare function createHttpCall(fetchFn?: typeof fetch, cacheStore?: CacheStore): ToolCallFn;
+/** Exported for testing. */
+export { parseCacheTTL };
+//# sourceMappingURL=http-call.d.ts.map

package/build/bridge-stdlib/src/tools/http-call.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-call.d.ts","sourceRoot":"","sources":["../../../../../bridge-stdlib/src/tools/http-call.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAgBvE;;;;;GAKG;AACH,iBAAS,aAAa,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAejD;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,cAAc,CAC5B,OAAO,GAAE,OAAO,KAAwB,EACxC,UAAU,GAAE,UAAgC,GAC3C,UAAU,CAkEZ;AAED,4BAA4B;AAC5B,OAAO,EAAE,aAAa,EAAE,CAAC"}

package/build/bridge-stdlib/src/tools/http-call.js

@@ -0,0 +1,118 @@
+import { LRUCache } from "lru-cache";
+/** Default in-memory LRU cache with per-entry TTL. */
+function createMemoryCache(maxEntries = 1024) {
+    const lru = new LRUCache({ max: maxEntries });
+    return {
+        get(key) {
+            return lru.get(key);
+        },
+        set(key, value, ttlSeconds) {
+            if (ttlSeconds <= 0)
+                return;
+            lru.set(key, value, { ttl: ttlSeconds * 1000 });
+        },
+    };
+}
+/**
+ * Parse TTL (in seconds) from HTTP response headers.
+ *
+ * Priority: `Cache-Control: s-maxage` > `Cache-Control: max-age` > `Expires`.
+ * Returns 0 if the response is uncacheable (no-store, no-cache, or no headers).
+ */
+function parseCacheTTL(response) {
+    const cc = response.headers.get("cache-control");
+    if (cc) {
+        if (/\bno-store\b/i.test(cc) || /\bno-cache\b/i.test(cc))
+            return 0;
+        const sMax = cc.match(/\bs-maxage\s*=\s*(\d+)\b/i);
+        if (sMax)
+            return Number(sMax[1]);
+        const max = cc.match(/\bmax-age\s*=\s*(\d+)\b/i);
+        if (max)
+            return Number(max[1]);
+    }
+    const expires = response.headers.get("expires");
+    if (expires) {
+        const delta = Math.floor((new Date(expires).getTime() - Date.now()) / 1000);
+        return delta > 0 ? delta : 0;
+    }
+    return 0;
+}
+/**
+ * Create an httpCall tool function — the built-in REST API tool.
+ *
+ * Receives a fully-built input object from the engine and makes an HTTP call.
+ * The engine resolves all wires (from tool definition + bridge wires) before calling.
+ *
+ * Expected input shape:
+ *   { baseUrl, method?, path?, headers?, cache?, ...shorthandFields }
+ *
+ * Routing rules:
+ *   - GET: shorthand fields → query string parameters
+ *   - POST/PUT/PATCH/DELETE: shorthand fields → JSON body
+ *   - `headers` object passed as HTTP headers
+ *   - `baseUrl` + `path` concatenated for the URL
+ *
+ * Cache modes:
+ *   - `cache = "auto"` (default) — respect HTTP Cache-Control / Expires headers
+ *   - `cache = 0` — disable caching entirely
+ *   - `cache = <seconds>` — explicit TTL override, ignores response headers
+ *
+ * @param fetchFn - Fetch implementation (override for testing)
+ * @param cacheStore - Pluggable cache store (default: in-memory LRU, 1024 entries)
+ */
+export function createHttpCall(fetchFn = globalThis.fetch, cacheStore = createMemoryCache()) {
+    return async (input) => {
+        const { baseUrl = "", method = "GET", path = "", headers: inputHeaders = {}, cache: cacheMode = "auto", ...rest } = input;
+        // Build URL
+        const url = new URL(baseUrl + path);
+        // Collect headers
+        const headers = {};
+        for (const [key, value] of Object.entries(inputHeaders)) {
+            if (value != null)
+                headers[key] = String(value);
+        }
+        // GET: shorthand fields → query string
+        if (method === "GET") {
+            for (const [key, value] of Object.entries(rest)) {
+                if (value != null) {
+                    url.searchParams.set(key, String(value));
+                }
+            }
+        }
+        // Non-GET: shorthand fields → JSON body
+        let body;
+        if (method !== "GET") {
+            const bodyObj = {};
+            for (const [key, value] of Object.entries(rest)) {
+                if (value != null)
+                    bodyObj[key] = value;
+            }
+            if (Object.keys(bodyObj).length > 0) {
+                body = JSON.stringify(bodyObj);
+                headers["Content-Type"] ??= "application/json";
+            }
+        }
+        // cache = 0 → no caching at all
+        const mode = String(cacheMode);
+        if (mode === "0") {
+            const response = await fetchFn(url.toString(), { method, headers, body });
+            return response.json();
+        }
+        const cacheKey = method + " " + url.toString() + (body ?? "");
+        // Check cache before fetching
+        const cached = await cacheStore.get(cacheKey);
+        if (cached !== undefined)
+            return cached;
+        const response = await fetchFn(url.toString(), { method, headers, body });
+        const data = (await response.json());
+        // Determine TTL
+        const ttl = mode === "auto" ? parseCacheTTL(response) : Number(mode);
+        if (ttl > 0) {
+            await cacheStore.set(cacheKey, data, ttl);
+        }
+        return data;
+    };
+}
+/** Exported for testing. */
+export { parseCacheTTL };

package/build/bridge-stdlib/src/tools/strings.d.ts

@@ -0,0 +1,13 @@
+export declare function toLowerCase(opts: {
+    in: string;
+}): string;
+export declare function toUpperCase(opts: {
+    in: string;
+}): string;
+export declare function trim(opts: {
+    in: string;
+}): string;
+export declare function length(opts: {
+    in: string;
+}): number;
+//# sourceMappingURL=strings.d.ts.map

package/build/bridge-stdlib/src/tools/strings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strings.d.ts","sourceRoot":"","sources":["../../../../../bridge-stdlib/src/tools/strings.ts"],"names":[],"mappings":"AAAA,wBAAgB,WAAW,CAAC,IAAI,EAAE;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,UAE/C;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,UAE/C;AAED,wBAAgB,IAAI,CAAC,IAAI,EAAE;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,UAExC;AAED,wBAAgB,MAAM,CAAC,IAAI,EAAE;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,UAE1C"}

package/build/bridge-stdlib/src/tools/strings.js

@@ -0,0 +1,12 @@
+export function toLowerCase(opts) {
+    return opts.in?.toLowerCase();
+}
+export function toUpperCase(opts) {
+    return opts.in?.toUpperCase();
+}
+export function trim(opts) {
+    return opts.in?.trim();
+}
+export function length(opts) {
+    return opts.in?.length;
+}

package/build/bridge-types/src/index.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @stackables/bridge-types — Shared type definitions for the Bridge ecosystem.
+ *
+ * These types are used by both bridge-core (engine) and bridge-stdlib (standard
+ * library tools). They live in a separate package to break the circular
+ * dependency between core and stdlib.
+ */
+/**
+ * Tool context — runtime services available to every tool call.
+ *
+ * Passed as the second argument to every ToolCallFn.
+ */
+export type ToolContext = {
+    /** Structured logger — same instance configured via `BridgeOptions.logger`.
+     *  Defaults to silent no-ops when no logger is configured. */
+    logger: {
+        debug?: (...args: any[]) => void;
+        info?: (...args: any[]) => void;
+        warn?: (...args: any[]) => void;
+        error?: (...args: any[]) => void;
+    };
+    /** External abort signal — allows the caller to cancel execution mid-flight.
+     *  When aborted, the engine short-circuits before starting new tool calls
+     *  and propagates the signal to tool implementations via this context field. */
+    signal?: AbortSignal;
+};
+/**
+ * Tool call function — the signature for registered tool functions.
+ *
+ * Receives a fully-built nested input object and an optional `ToolContext`
+ * providing access to the engine's logger and other services.
+ *
+ * Example (httpCall):
+ *   input = { baseUrl: "https://...", method: "GET", path: "/geocode",
+ *             headers: { apiKey: "..." }, q: "Berlin" }
+ */
+export type ToolCallFn = (input: Record<string, any>, context?: ToolContext) => Promise<Record<string, any>>;
+/**
+ * Recursive tool map — supports namespaced tools via nesting.
+ *
+ * Example:
+ *   { std: { upperCase, lowerCase }, httpCall: createHttpCall(), myCompany: { myTool } }
+ *
+ * Lookup is dot-separated: "std.str.toUpperCase" → tools.std.str.toUpperCase
+ */
+export type ToolMap = {
+    [key: string]: ToolCallFn | ((...args: any[]) => any) | ToolMap;
+};
+/**
+ * Pluggable cache store for httpCall.
+ *
+ * Default: in-memory Map with TTL eviction.
+ * Override: pass any key-value store (Redis, Memcached, etc.) to `createHttpCall`.
+ *
+ * ```ts
+ * const httpCall = createHttpCall(fetch, myRedisStore);
+ * ```
+ */
+export type CacheStore = {
+    get(key: string): Promise<any | undefined> | any | undefined;
+    set(key: string, value: any, ttlSeconds: number): Promise<void> | void;
+};
+//# sourceMappingURL=index.d.ts.map

package/build/bridge-types/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../bridge-types/src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB;kEAC8D;IAC9D,MAAM,EAAE;QACN,KAAK,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;QACjC,IAAI,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;QAChC,IAAI,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;QAChC,KAAK,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;KAClC,CAAC;IACF;;oFAEgF;IAChF,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,MAAM,UAAU,GAAG,CACvB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC1B,OAAO,CAAC,EAAE,WAAW,KAClB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;AAElC;;;;;;;GAOG;AACH,MAAM,MAAM,OAAO,GAAG;IACpB,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,GAAG,OAAO,CAAC;CACjE,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,GAAG,SAAS,CAAC,GAAG,GAAG,GAAG,SAAS,CAAC;IAC7D,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACxE,CAAC"}

package/build/bridge-types/src/index.js

@@ -0,0 +1,8 @@
+/**
+ * @stackables/bridge-types — Shared type definitions for the Bridge ecosystem.
+ *
+ * These types are used by both bridge-core (engine) and bridge-stdlib (standard
+ * library tools). They live in a separate package to break the circular
+ * dependency between core and stdlib.
+ */
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackables/bridge-graphql",
-  "version": "0.0.1",
+  "version": "1.0.1",
   "description": "Bridge GraphQL adapter — wire bridges into a GraphQL schema",
   "main": "./build/index.js",
   "type": "module",
@@ -22,8 +22,8 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@stackables/bridge-stdlib": "0.0.1",
-    "@stackables/bridge-core": "0.0.1"
+    "@stackables/bridge-core": "1.0.1",
+    "@stackables/bridge-stdlib": "1.5.0"
   },
   "devDependencies": {
     "typescript": "^5.9.3"

package/build/bridge-transform.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"bridge-transform.d.ts","sourceRoot":"","sources":["../src/bridge-transform.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,aAAa,EAEnB,MAAM,SAAS,CAAC;AACjB,OAAO,EAGL,KAAK,MAAM,EACX,KAAK,SAAS,EACd,KAAK,UAAU,EAChB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAGpE,YAAY,EAAE,MAAM,EAAE,CAAC;AAUvB,MAAM,MAAM,aAAa,GAAG;IAC1B;;;kDAG8C;IAC9C,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;qEACiE;IACjE,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,KAAK,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACtD;;;6DAGyD;IACzD,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,gFAAgF;AAChF,MAAM,MAAM,iBAAiB,GACzB,WAAW,EAAE,GACb,CAAC,CAAC,OAAO,EAAE,GAAG,KAAK,WAAW,EAAE,CAAC,CAAC;AAEtC,wBAAgB,eAAe,CAC7B,MAAM,EAAE,aAAa,EACrB,YAAY,EAAE,iBAAiB,EAC/B,OAAO,CAAC,EAAE,aAAa,GACtB,aAAa,CAqHf;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,GAAG,GAAG,SAAS,EAAE,CAEzD;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB;wBAER;QAAE,IAAI,EAAE;YAAE,YAAY,EAAE,GAAG,CAAA;SAAE,CAAA;KAAE;8CAK5C;YACD,MAAM,EAAE,GAAG,CAAC;YACZ,SAAS,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,IAAI,CAAC;SAC7B;;EAeR"}