flowflex 0.1.0

package/dist/client.js

@@ -0,0 +1,311 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlowFlex = void 0;
+const file_js_1 = require("./file.js");
+const errors_js_1 = require("./errors.js");
+/** 25 MB — mirrors the backend's asset size limit. */
+const DEFAULT_MAX_FILE_BYTES = 25 * 1024 * 1024;
+/** Base64-encode `key:secret` for HTTP Basic auth, in Node or the browser. */
+function basicAuth(key, secret) {
+    const raw = `${key}:${secret}`;
+    if (typeof Buffer !== "undefined")
+        return Buffer.from(raw).toString("base64");
+    // Browser fallback.
+    return btoa(raw);
+}
+/** True when running in a browser-like environment (has window + document). */
+function isBrowser() {
+    return (typeof window !== "undefined" &&
+        typeof window.document !== "undefined");
+}
+/** A loopback host is safe to use over plain HTTP in development. */
+function isLoopbackHost(host) {
+    return host === "localhost" || host === "127.0.0.1" || host === "[::1]" || host === "::1";
+}
+/**
+ * Reject values that would break out of an HTTP header (CRLF / control chars)
+ * — prevents header-injection via the event name or idempotency key.
+ */
+function assertSafeHeaderValue(label, value) {
+    if (/[\r\n\x00-\x1f\x7f]/.test(value)) {
+        throw new errors_js_1.FlowFlexConfigError(`${label} contains invalid control characters`);
+    }
+}
+/**
+ * Assign onto a plain object without the `__proto__` prototype-pollution
+ * footgun (and treats `constructor`/`prototype` as ordinary own keys too).
+ */
+function safeSet(obj, key, value) {
+    if (key === "__proto__" || key === "constructor" || key === "prototype") {
+        Object.defineProperty(obj, key, {
+            value,
+            enumerable: true,
+            writable: true,
+            configurable: true,
+        });
+    }
+    else {
+        obj[key] = value;
+    }
+}
+/** RFC4122-ish UUID using the platform crypto, with a non-crypto fallback. */
+function uuid() {
+    const c = globalThis.crypto;
+    if (c?.randomUUID)
+        return c.randomUUID();
+    return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (ch) => {
+        const r = Math.floor(Math.random() * 16);
+        const v = ch === "x" ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}
+class FlowFlex {
+    constructor(options) {
+        const { apiKey, apiSecret, integrationCode, baseUrl } = options;
+        if (!apiKey)
+            throw new errors_js_1.FlowFlexConfigError("apiKey is required");
+        if (!apiSecret)
+            throw new errors_js_1.FlowFlexConfigError("apiSecret is required");
+        if (!integrationCode)
+            throw new errors_js_1.FlowFlexConfigError("integrationCode is required");
+        if (!baseUrl)
+            throw new errors_js_1.FlowFlexConfigError("baseUrl is required");
+        // Hard block: the SDK is server-only. The api key/secret are
+        // integration-wide credentials and must never reach client code.
+        // (Browser bundles can't even import this module — see package.json's
+        // "browser" export condition, which resolves to a throwing stub.)
+        if (isBrowser()) {
+            throw new errors_js_1.FlowFlexConfigError("FlowFlex is server-only and cannot run in a browser. It authenticates with " +
+                "your integration apiKey/apiSecret over HTTP Basic auth — exposing those in " +
+                "client code lets anyone fire events as you. Call the SDK from your server " +
+                "and have the browser talk to your own backend endpoint.");
+        }
+        // Validate baseUrl and enforce HTTPS off-loopback so Basic-auth
+        // credentials are never sent in cleartext.
+        const stripped = baseUrl.replace(/\/api\/?$/, "").replace(/\/$/, "");
+        let parsed;
+        try {
+            parsed = new URL(stripped);
+        }
+        catch {
+            throw new errors_js_1.FlowFlexConfigError(`baseUrl is not a valid URL: "${baseUrl}"`);
+        }
+        if (parsed.protocol !== "https:" && !isLoopbackHost(parsed.hostname)) {
+            throw new errors_js_1.FlowFlexConfigError(`baseUrl must use https (got "${parsed.protocol}//${parsed.hostname}"). ` +
+                "Basic-auth credentials would otherwise be sent in cleartext. " +
+                "Plain http is only allowed for localhost.");
+        }
+        const f = options.fetch ?? globalThis.fetch;
+        if (typeof f !== "function") {
+            throw new errors_js_1.FlowFlexConfigError("No fetch implementation found — upgrade to Node 18+ or pass { fetch }");
+        }
+        this.apiKey = apiKey;
+        this.apiSecret = apiSecret;
+        this.integrationCode = integrationCode;
+        this.baseUrl = stripped;
+        this.timeoutMs = options.timeoutMs ?? 30000;
+        this.maxFileBytes = options.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES;
+        // Bind to the global scope. The browser's native `fetch` throws
+        // "Illegal invocation" if called as a method on another object
+        // (i.e. `this.fetchImpl(...)`), so we detach it from `this`.
+        this.fetchImpl = f.bind(globalThis);
+    }
+    /** Convenience re-export so callers can do `ff.file(...)`. */
+    file(source, options) {
+        return (0, file_js_1.file)(source, options);
+    }
+    authHeader() {
+        return `Basic ${basicAuth(this.apiKey, this.apiSecret)}`;
+    }
+    /** fetch wrapper with timeout + JSON parsing + error normalization. */
+    async request(url, init) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        let res;
+        try {
+            res = await this.fetchImpl(url, { ...init, signal: controller.signal });
+        }
+        catch (err) {
+            if (err?.name === "AbortError") {
+                throw new errors_js_1.FlowFlexError(`Request to ${url} timed out after ${this.timeoutMs}ms`);
+            }
+            throw new errors_js_1.FlowFlexError(`Network error calling ${url}: ${err?.message || err}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const text = await res.text();
+        let body = text;
+        if (text && (res.headers.get("content-type") || "").includes("application/json")) {
+            try {
+                body = JSON.parse(text);
+            }
+            catch {
+                /* leave as text */
+            }
+        }
+        if (!res.ok) {
+            const message = (body && typeof body === "object" && (body.error || body.message)) ||
+                `Request to ${url} failed with status ${res.status}`;
+            throw new errors_js_1.FlowFlexError(String(message), {
+                status: res.status,
+                code: body?.code || body?.name,
+                details: body,
+            });
+        }
+        return body;
+    }
+    /**
+     * Request a presigned upload URL. Most callers don't need this directly —
+     * use `file()` inside an event payload and let `sendEvent` handle uploads.
+     */
+    async createUploadUrl(input) {
+        return this.request(`${this.baseUrl}/v1/assets/upload-url`, {
+            method: "POST",
+            headers: {
+                Authorization: this.authHeader(),
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(input),
+        });
+    }
+    /** Upload one FileRef and return its assetId. */
+    async uploadFile(ref) {
+        const blob = await ref.toBlob();
+        // Fail fast on oversized files instead of uploading then being rejected.
+        if (blob.size > this.maxFileBytes) {
+            throw new errors_js_1.FlowFlexUploadError(`"${ref.filename}" is ${blob.size} bytes, over the ${this.maxFileBytes}-byte limit`);
+        }
+        const { assetId, uploadUrl } = await this.createUploadUrl({
+            filename: ref.filename,
+            mime: ref.mime,
+            size: ref.size,
+        });
+        // PUT the raw bytes straight to storage. No auth header — the presigned
+        // URL carries its own token, and an extra Authorization breaks it.
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        let res;
+        try {
+            res = await this.fetchImpl(uploadUrl, {
+                method: "PUT",
+                headers: { "Content-Type": ref.mime },
+                body: blob,
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            throw new errors_js_1.FlowFlexUploadError(`Failed to upload "${ref.filename}": ${err?.message || err}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!res.ok) {
+            const detail = await res.text().catch(() => "");
+            throw new errors_js_1.FlowFlexUploadError(`Storage rejected upload of "${ref.filename}" (status ${res.status})`, { status: res.status, details: detail });
+        }
+        return assetId;
+    }
+    /**
+     * Deep-clone a payload, collecting every FileRef anywhere inside it (nested
+     * objects, arrays, mixed) alongside its parent container + key so we can
+     * patch the assetId back in after upload. The container always exists at
+     * push time, so there's no backfill to get wrong.
+     */
+    cloneAndCollect(value, path, refs) {
+        // A bare FileRef (e.g. the whole payload is a file) — caller decides.
+        if (value instanceof file_js_1.FileRef)
+            return value;
+        if (Array.isArray(value)) {
+            const arr = new Array(value.length);
+            value.forEach((v, i) => {
+                const p = `${path}[${i}]`;
+                if (v instanceof file_js_1.FileRef) {
+                    arr[i] = null; // placeholder, patched after upload
+                    refs.push({ container: arr, key: i, ref: v, path: p });
+                }
+                else {
+                    arr[i] = this.cloneAndCollect(v, p, refs);
+                }
+            });
+            return arr;
+        }
+        if (value && typeof value === "object") {
+            const out = {};
+            for (const [k, v] of Object.entries(value)) {
+                const p = path ? `${path}.${k}` : k;
+                if (v instanceof file_js_1.FileRef) {
+                    refs.push({ container: out, key: k, ref: v, path: p });
+                }
+                else {
+                    safeSet(out, k, this.cloneAndCollect(v, p, refs));
+                }
+            }
+            return out;
+        }
+        return value;
+    }
+    /**
+     * Upload every FileRef in a payload and return a deep copy with each replaced
+     * by its assetId string, plus a map of path → assetId. Uploads run in
+     * parallel; the SAME FileRef instance reused in multiple places is uploaded
+     * only once and its assetId reused everywhere.
+     */
+    async resolveFiles(payload) {
+        const refs = [];
+        const resolved = this.cloneAndCollect(payload, "", refs);
+        // Dedupe by FileRef identity so reusing one file() across nodes uploads once.
+        const uniqueRefs = [...new Set(refs.map((r) => r.ref))];
+        const idByRef = new Map();
+        await Promise.all(uniqueRefs.map(async (ref) => {
+            idByRef.set(ref, await this.uploadFile(ref));
+        }));
+        const uploaded = {};
+        for (const { container, key, ref, path } of refs) {
+            const assetId = idByRef.get(ref);
+            if (typeof key === "number") {
+                container[key] = assetId; // array index — safe
+            }
+            else {
+                safeSet(container, key, assetId);
+            }
+            uploaded[path] = assetId;
+        }
+        return { resolved, uploaded };
+    }
+    /**
+     * Fire a custom-integration event into FlowFlex. Any `file()` in the payload
+     * is uploaded first and replaced with its assetId, so a flow's media node can
+     * reference it as e.g. `{{trigger.assetId}}`.
+     *
+     * @example
+     *   await ff.sendEvent("invoice.created", {
+     *     payload: { assetId: ff.file("./invoice.pdf"), name: "Ada" },
+     *   });
+     */
+    async sendEvent(event, body = {}) {
+        if (!event)
+            throw new errors_js_1.FlowFlexError("event name is required");
+        const { payload = {}, idempotencyKey } = body;
+        // These flow into HTTP headers — reject control characters (CRLF) to
+        // prevent header injection.
+        assertSafeHeaderValue("event", event);
+        const idemKey = idempotencyKey || uuid();
+        assertSafeHeaderValue("idempotencyKey", idemKey);
+        const { resolved, uploaded } = await this.resolveFiles(payload);
+        const response = await this.request(
+        // Encode the code so it can't break out of the URL path.
+        `${this.baseUrl}/v1/events/${encodeURIComponent(this.integrationCode)}`, {
+            method: "POST",
+            headers: {
+                Authorization: this.authHeader(),
+                "Content-Type": "application/json",
+                "x-event": event,
+                "x-idempotency-key": idemKey,
+            },
+            body: JSON.stringify(resolved),
+        });
+        return { response, uploadedAssets: uploaded };
+    }
+}
+exports.FlowFlex = FlowFlex;

package/dist/errors.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Base error for every failure raised by the SDK. Carries the HTTP status (when
+ * the failure came from an API call) and the machine-readable code returned by
+ * the backend (e.g. "MIME_NOT_ALLOWED", "ASSET_FILE_MISSING").
+ */
+export declare class FlowFlexError extends Error {
+    /** HTTP status code, if the error originated from an API response. */
+    readonly status?: number;
+    /** Machine-readable error code from the backend, if any. */
+    readonly code?: string;
+    /** Raw response body, for debugging. */
+    readonly details?: unknown;
+    constructor(message: string, opts?: {
+        status?: number;
+        code?: string;
+        details?: unknown;
+    });
+}
+/** Thrown when the SDK is constructed with missing/invalid configuration. */
+export declare class FlowFlexConfigError extends FlowFlexError {
+    constructor(message: string);
+}
+/** Thrown when a file attachment cannot be uploaded. */
+export declare class FlowFlexUploadError extends FlowFlexError {
+    constructor(message: string, opts?: {
+        status?: number;
+        code?: string;
+        details?: unknown;
+    });
+}

package/dist/errors.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlowFlexUploadError = exports.FlowFlexConfigError = exports.FlowFlexError = void 0;
+/**
+ * Base error for every failure raised by the SDK. Carries the HTTP status (when
+ * the failure came from an API call) and the machine-readable code returned by
+ * the backend (e.g. "MIME_NOT_ALLOWED", "ASSET_FILE_MISSING").
+ */
+class FlowFlexError extends Error {
+    constructor(message, opts = {}) {
+        super(message);
+        this.name = "FlowFlexError";
+        this.status = opts.status;
+        this.code = opts.code;
+        this.details = opts.details;
+    }
+}
+exports.FlowFlexError = FlowFlexError;
+/** Thrown when the SDK is constructed with missing/invalid configuration. */
+class FlowFlexConfigError extends FlowFlexError {
+    constructor(message) {
+        super(message);
+        this.name = "FlowFlexConfigError";
+    }
+}
+exports.FlowFlexConfigError = FlowFlexConfigError;
+/** Thrown when a file attachment cannot be uploaded. */
+class FlowFlexUploadError extends FlowFlexError {
+    constructor(message, opts = {}) {
+        super(message, opts);
+        this.name = "FlowFlexUploadError";
+    }
+}
+exports.FlowFlexUploadError = FlowFlexUploadError;

package/dist/esm/browser.js

@@ -0,0 +1,43 @@
+/**
+ * Browser build of `flowflex` — intentionally non-functional.
+ *
+ * Bundlers that target the browser resolve the package to this module via the
+ * `"browser"` export condition (and legacy `"browser"` field) in package.json.
+ *
+ * The SDK is **server-only**: it authenticates with your integration
+ * `apiKey`/`apiSecret` over HTTP Basic auth, and those credentials must never
+ * reach client code. Importing or using it in the browser throws immediately.
+ * Call the SDK from your backend (e.g. a Next.js route handler / API route) and
+ * have the browser talk to your own server endpoint instead.
+ */
+const MESSAGE = "flowflex is server-only and must not be bundled into browser/client code. " +
+    "It uses your integration apiKey/apiSecret over HTTP Basic auth — exposing those in the " +
+    "browser lets anyone fire events as you. Call the SDK from your server (e.g. a Next.js " +
+    "route handler / API route) and have the browser talk to your own backend endpoint.";
+export class FlowFlexError extends Error {
+    constructor(message = MESSAGE) {
+        super(message);
+        this.name = "FlowFlexError";
+    }
+}
+export class FlowFlexConfigError extends FlowFlexError {
+}
+export class FlowFlexUploadError extends FlowFlexError {
+}
+export class FlowFlex {
+    constructor() {
+        throw new FlowFlexConfigError(MESSAGE);
+    }
+}
+export class FileRef {
+    constructor() {
+        throw new FlowFlexConfigError(MESSAGE);
+    }
+}
+export function file() {
+    throw new FlowFlexConfigError(MESSAGE);
+}
+export default FlowFlex;
+// Fail loudly the moment this server-only module is evaluated in a browser
+// bundle — before any FlowFlex is even constructed.
+throw new FlowFlexConfigError(MESSAGE);