@blokjs/shared 0.6.12 → 0.6.14

package/dist/index.d.ts

@@ -13,6 +13,7 @@ import FunctionContext from "./types/FunctionContext";
 import LoggerContext from "./types/LoggerContext";
 import NodeConfigContext from "./types/NodeConfigContext";
 import RequestContext from "./types/RequestContext";
+import { RESPOND_BRAND, type RespondEnvelope, isRespondEnvelope } from "./types/RespondEnvelope";
 import ResponseContext from "./types/ResponseContext";
 import StateContext from "./types/StateContext";
 import Step from "./types/Step";
@@ -20,4 +21,4 @@ import type StreamContext from "./types/StreamContext";
 import VarsContext from "./types/VarsContext";
 import mapper from "./utils/Mapper";
 import MemoryUsage from "./utils/MemoryUsage";
-export { NodeBase, Context, RequestContext, ResponseContext, EnvContext, ErrorContext, LoggerContext, ConfigContext, type ConnectionContext, type StreamContext, Trigger, NodeConfigContext, FunctionContext, StateContext, VarsContext, Step, GlobalLogger, GlobalError, BlokError, type BlokErrorOpts, type NodeErrorPayload, ErrorCategory, ErrorSeverity, DEFAULT_HTTP_STATUS, DEFAULT_RETRYABLE, Metrics, MemoryUsage, type MetricsType, mapper, };
+export { NodeBase, Context, RequestContext, ResponseContext, RESPOND_BRAND, type RespondEnvelope, isRespondEnvelope, EnvContext, ErrorContext, LoggerContext, ConfigContext, type ConnectionContext, type StreamContext, Trigger, NodeConfigContext, FunctionContext, StateContext, VarsContext, Step, GlobalLogger, GlobalError, BlokError, type BlokErrorOpts, type NodeErrorPayload, ErrorCategory, ErrorSeverity, DEFAULT_HTTP_STATUS, DEFAULT_RETRYABLE, Metrics, MemoryUsage, type MetricsType, mapper, };

package/dist/index.js

@@ -4,7 +4,8 @@ import GlobalLogger from "./GlobalLogger";
 import { Metrics } from "./Metrics";
 import NodeBase from "./NodeBase";
 import Trigger from "./Trigger";
+import { RESPOND_BRAND, isRespondEnvelope } from "./types/RespondEnvelope";
 import mapper from "./utils/Mapper";
 import MemoryUsage from "./utils/MemoryUsage";
-export { NodeBase, Trigger, GlobalLogger, GlobalError, BlokError, ErrorCategory, ErrorSeverity, DEFAULT_HTTP_STATUS, DEFAULT_RETRYABLE, Metrics, MemoryUsage, mapper, };
+export { NodeBase, RESPOND_BRAND, isRespondEnvelope, Trigger, GlobalLogger, GlobalError, BlokError, ErrorCategory, ErrorSeverity, DEFAULT_HTTP_STATUS, DEFAULT_RETRYABLE, Metrics, MemoryUsage, mapper, };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,EAAE,EAEjB,mBAAmB,EACnB,iBAAiB,EACjB,aAAa,EACb,aAAa,GAEb,MAAM,aAAa,CAAC;AACrB,OAAO,WAAW,MAAM,eAAe,CAAC;AACxC,OAAO,YAAY,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAoB,MAAM,WAAW,CAAC;AACtD,OAAO,QAAQ,MAAM,YAAY,CAAC;AAClC,OAAO,OAAO,MAAM,WAAW,CAAC;AAehC,OAAO,MAAM,MAAM,gBAAgB,CAAC;AACpC,OAAO,WAAW,MAAM,qBAAqB,CAAC;AAE9C,OAAO,EACN,QAAQ,EAUR,OAAO,EAMP,YAAY,EACZ,WAAW,EACX,SAAS,EAGT,aAAa,EACb,aAAa,EACb,mBAAmB,EACnB,iBAAiB,EACjB,OAAO,EACP,WAAW,EAEX,MAAM,GACN,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,EAAE,EAEjB,mBAAmB,EACnB,iBAAiB,EACjB,aAAa,EACb,aAAa,GAEb,MAAM,aAAa,CAAC;AACrB,OAAO,WAAW,MAAM,eAAe,CAAC;AACxC,OAAO,YAAY,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAoB,MAAM,WAAW,CAAC;AACtD,OAAO,QAAQ,MAAM,YAAY,CAAC;AAClC,OAAO,OAAO,MAAM,WAAW,CAAC;AAUhC,OAAO,EAAE,aAAa,EAAwB,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAMjG,OAAO,MAAM,MAAM,gBAAgB,CAAC;AACpC,OAAO,WAAW,MAAM,qBAAqB,CAAC;AAE9C,OAAO,EACN,QAAQ,EAIR,aAAa,EAEb,iBAAiB,EAOjB,OAAO,EAMP,YAAY,EACZ,WAAW,EACX,SAAS,EAGT,aAAa,EACb,aAAa,EACb,mBAAmB,EACnB,iBAAiB,EACjB,OAAO,EACP,WAAW,EAEX,MAAM,GACN,CAAC"}

package/dist/types/RespondEnvelope.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Branded HTTP-response envelope.
+ *
+ * A workflow step (typically the `@blokjs/respond` node, as the final step)
+ * returns a `RespondEnvelope` to control the full HTTP response — status code,
+ * arbitrary headers (incl. `Location` for redirects), repeatable `Set-Cookie`
+ * values, the body, and the `Content-Type`. The `http` trigger recognizes the
+ * brand on the final `ctx.response.data` and unpacks it; any non-branded result
+ * keeps the default behaviour (JSON / string body, status 200).
+ *
+ * The envelope is the carrier for *dynamic* response metadata (status/headers
+ * depend on runtime inputs, so they can't ride a static node field like
+ * `contentType`). It travels as ordinary step data — no `ctx` mutation, no
+ * runner-core changes — so the mechanism is fully additive and HTTP-specific.
+ */
+export declare const RESPOND_BRAND: "__blokRespond__";
+export interface RespondEnvelope {
+    readonly [RESPOND_BRAND]: true;
+    /**
+     * Response body. `string` → written verbatim; `Uint8Array`/`Buffer`/
+     * `ArrayBuffer` → written as raw bytes; any other value → JSON-encoded.
+     * Omit (or `null`/`undefined`) for empty-body responses (e.g. a 302).
+     */
+    body?: unknown;
+    /** HTTP status code. Defaults to 200. */
+    status?: number;
+    /**
+     * Content-Type. Overrides the default. When omitted: `application/json`
+     * for object bodies, `application/octet-stream` for binary bodies.
+     */
+    contentType?: string;
+    /** Response headers, e.g. `{ Location: "/next" }` or `{ "Content-Disposition": "attachment; filename=\"x.pdf\"" }`. */
+    headers?: Record<string, string>;
+    /**
+     * Raw `Set-Cookie` header values. Each entry becomes its own `Set-Cookie`
+     * header (the header legitimately repeats), so a single response can set
+     * multiple cookies. Format each value yourself, e.g.
+     * `"session=abc; Path=/; HttpOnly; SameSite=Lax"`.
+     */
+    cookies?: string[];
+}
+/**
+ * Type guard: is `value` a branded {@link RespondEnvelope}? Used by the `http`
+ * trigger to decide whether to unpack response metadata or fall through to the
+ * default JSON/string/binary handling.
+ */
+export declare function isRespondEnvelope(value: unknown): value is RespondEnvelope;
+export default RespondEnvelope;

package/dist/types/RespondEnvelope.js

@@ -0,0 +1,25 @@
+/**
+ * Branded HTTP-response envelope.
+ *
+ * A workflow step (typically the `@blokjs/respond` node, as the final step)
+ * returns a `RespondEnvelope` to control the full HTTP response — status code,
+ * arbitrary headers (incl. `Location` for redirects), repeatable `Set-Cookie`
+ * values, the body, and the `Content-Type`. The `http` trigger recognizes the
+ * brand on the final `ctx.response.data` and unpacks it; any non-branded result
+ * keeps the default behaviour (JSON / string body, status 200).
+ *
+ * The envelope is the carrier for *dynamic* response metadata (status/headers
+ * depend on runtime inputs, so they can't ride a static node field like
+ * `contentType`). It travels as ordinary step data — no `ctx` mutation, no
+ * runner-core changes — so the mechanism is fully additive and HTTP-specific.
+ */
+export const RESPOND_BRAND = "__blokRespond__";
+/**
+ * Type guard: is `value` a branded {@link RespondEnvelope}? Used by the `http`
+ * trigger to decide whether to unpack response metadata or fall through to the
+ * default JSON/string/binary handling.
+ */
+export function isRespondEnvelope(value) {
+    return (typeof value === "object" && value !== null && value[RESPOND_BRAND] === true);
+}
+//# sourceMappingURL=RespondEnvelope.js.map

package/dist/types/RespondEnvelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RespondEnvelope.js","sourceRoot":"","sources":["../../src/types/RespondEnvelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,iBAA0B,CAAC;AA4BxD;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC/C,OAAO,CACN,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAK,KAA0C,CAAC,aAAa,CAAC,KAAK,IAAI,CAClH,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@blokjs/shared",
-	"version": "0.6.12",
+	"version": "0.6.14",
 	"description": "Shared class, interfaces and types",
 	"type": "module",
 	"main": "dist/index.js",