flowflex 0.1.0

package/dist/esm/client.js

@@ -0,0 +1,307 @@
+import { FileRef, file as makeFile } from "./file.js";
+import { FlowFlexConfigError, FlowFlexError, FlowFlexUploadError } from "./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 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);
+    });
+}
+export class FlowFlex {
+    constructor(options) {
+        const { apiKey, apiSecret, integrationCode, baseUrl } = options;
+        if (!apiKey)
+            throw new FlowFlexConfigError("apiKey is required");
+        if (!apiSecret)
+            throw new FlowFlexConfigError("apiSecret is required");
+        if (!integrationCode)
+            throw new FlowFlexConfigError("integrationCode is required");
+        if (!baseUrl)
+            throw new 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 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 FlowFlexConfigError(`baseUrl is not a valid URL: "${baseUrl}"`);
+        }
+        if (parsed.protocol !== "https:" && !isLoopbackHost(parsed.hostname)) {
+            throw new 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 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 makeFile(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 FlowFlexError(`Request to ${url} timed out after ${this.timeoutMs}ms`);
+            }
+            throw new 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 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 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 FlowFlexUploadError(`Failed to upload "${ref.filename}": ${err?.message || err}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!res.ok) {
+            const detail = await res.text().catch(() => "");
+            throw new 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 FileRef)
+            return value;
+        if (Array.isArray(value)) {
+            const arr = new Array(value.length);
+            value.forEach((v, i) => {
+                const p = `${path}[${i}]`;
+                if (v instanceof 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 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 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 };
+    }
+}

package/dist/esm/errors.js

@@ -0,0 +1,28 @@
+/**
+ * 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 class FlowFlexError extends Error {
+    constructor(message, opts = {}) {
+        super(message);
+        this.name = "FlowFlexError";
+        this.status = opts.status;
+        this.code = opts.code;
+        this.details = opts.details;
+    }
+}
+/** Thrown when the SDK is constructed with missing/invalid configuration. */
+export class FlowFlexConfigError extends FlowFlexError {
+    constructor(message) {
+        super(message);
+        this.name = "FlowFlexConfigError";
+    }
+}
+/** Thrown when a file attachment cannot be uploaded. */
+export class FlowFlexUploadError extends FlowFlexError {
+    constructor(message, opts = {}) {
+        super(message, opts);
+        this.name = "FlowFlexUploadError";
+    }
+}

package/dist/esm/file.js

@@ -0,0 +1,113 @@
+import { FlowFlexUploadError } from "./errors.js";
+/** Maps common extensions → MIME types accepted by the FlowFlex assets API. */
+const EXT_TO_MIME = {
+    pdf: "application/pdf",
+    doc: "application/msword",
+    docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    xls: "application/vnd.ms-excel",
+    xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    ppt: "application/vnd.ms-powerpoint",
+    pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    txt: "text/plain",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    png: "image/png",
+    mp4: "video/mp4",
+    "3gp": "video/3gpp",
+    aac: "audio/aac",
+    amr: "audio/amr",
+    mp3: "audio/mpeg",
+    ogg: "audio/ogg",
+};
+function inferMimeFromName(name) {
+    const ext = name.split(".").pop()?.toLowerCase();
+    return ext ? EXT_TO_MIME[ext] : undefined;
+}
+function basename(p) {
+    return p.split(/[\\/]/).pop() || p;
+}
+/**
+ * A lazy reference to a file the caller wants to attach to an event. The bytes
+ * are not read until the event is sent. Create one with `FlowFlex.file()` or
+ * the standalone `file()` helper.
+ */
+export class FileRef {
+    constructor(source, options = {}) {
+        this.source = source;
+        this.options = options;
+    }
+    /** Resolve the filename, inferring from a path source when possible. */
+    get filename() {
+        if (this.options.filename)
+            return this.options.filename;
+        if (typeof this.source === "string")
+            return basename(this.source);
+        const blobName = this.source?.name;
+        if (blobName)
+            return blobName;
+        throw new FlowFlexUploadError("Cannot determine filename for attachment — pass { filename } to file()");
+    }
+    /** Resolve the MIME type, inferring from the filename when possible. */
+    get mime() {
+        if (this.options.mime)
+            return this.options.mime;
+        const blobType = this.source?.type;
+        if (blobType)
+            return blobType;
+        const inferred = inferMimeFromName(this.filename);
+        if (inferred)
+            return inferred;
+        throw new FlowFlexUploadError(`Cannot determine MIME type for "${this.filename}" — pass { mime } to file()`);
+    }
+    get size() {
+        if (typeof this.options.size === "number")
+            return this.options.size;
+        if (this.source instanceof Uint8Array)
+            return this.source.byteLength;
+        if (typeof Blob !== "undefined" && this.source instanceof Blob)
+            return this.source.size;
+        return undefined;
+    }
+    /**
+     * Read the file bytes as a Blob, ready to PUT to storage. On Node a string
+     * source is read from disk via `fs`; Buffers/Uint8Arrays/Blobs are wrapped.
+     */
+    async toBlob() {
+        const { source, mime } = { source: this.source, mime: this.mime };
+        if (typeof source === "string") {
+            // Node-only: read from disk. The indirect specifier + @vite-ignore
+            // stops browser bundlers (Vite/esbuild) from trying to resolve
+            // "fs/promises" at build time — this branch never runs in a browser.
+            let fs;
+            const fsSpecifier = "fs/promises";
+            try {
+                fs = await import(/* @vite-ignore */ /* webpackIgnore: true */ fsSpecifier);
+            }
+            catch {
+                throw new FlowFlexUploadError("File paths are only supported on Node.js — pass a Blob/File in the browser");
+            }
+            const buf = await fs.readFile(source);
+            return new Blob([new Uint8Array(buf)], { type: mime });
+        }
+        if (typeof Blob !== "undefined" && source instanceof Blob) {
+            return source;
+        }
+        if (source instanceof Uint8Array) {
+            // Covers Buffer too (Buffer extends Uint8Array).
+            return new Blob([source], { type: mime });
+        }
+        throw new FlowFlexUploadError("Unsupported file source");
+    }
+}
+/**
+ * Wrap a file so it can be attached to an event payload. The SDK uploads it via
+ * a presigned URL when the event is sent and swaps it for its `assetId`.
+ *
+ * @example
+ *   ff.sendEvent("invoice.created", {
+ *     payload: { assetId: file("./invoice.pdf"), customer_id: "cust_123" },
+ *   });
+ */
+export function file(source, options) {
+    return new FileRef(source, options);
+}

package/dist/esm/index.js

@@ -0,0 +1,5 @@
+export { FlowFlex } from "./client.js";
+export { file, FileRef } from "./file.js";
+export { FlowFlexError, FlowFlexConfigError, FlowFlexUploadError, } from "./errors.js";
+import { FlowFlex } from "./client.js";
+export default FlowFlex;

package/dist/esm/package.json

@@ -0,0 +1 @@
+{"type":"module"}

package/dist/esm/types.js

@@ -0,0 +1 @@
+export {};

package/dist/file.d.ts

@@ -0,0 +1,33 @@
+import { FileOptions } from "./types.js";
+/** Accepted file sources. */
+export type FileSource = string | Buffer | Uint8Array | Blob;
+/**
+ * A lazy reference to a file the caller wants to attach to an event. The bytes
+ * are not read until the event is sent. Create one with `FlowFlex.file()` or
+ * the standalone `file()` helper.
+ */
+export declare class FileRef {
+    readonly source: FileSource;
+    private readonly options;
+    constructor(source: FileSource, options?: FileOptions);
+    /** Resolve the filename, inferring from a path source when possible. */
+    get filename(): string;
+    /** Resolve the MIME type, inferring from the filename when possible. */
+    get mime(): string;
+    get size(): number | undefined;
+    /**
+     * Read the file bytes as a Blob, ready to PUT to storage. On Node a string
+     * source is read from disk via `fs`; Buffers/Uint8Arrays/Blobs are wrapped.
+     */
+    toBlob(): Promise<Blob>;
+}
+/**
+ * Wrap a file so it can be attached to an event payload. The SDK uploads it via
+ * a presigned URL when the event is sent and swaps it for its `assetId`.
+ *
+ * @example
+ *   ff.sendEvent("invoice.created", {
+ *     payload: { assetId: file("./invoice.pdf"), customer_id: "cust_123" },
+ *   });
+ */
+export declare function file(source: FileSource, options?: FileOptions): FileRef;

package/dist/file.js

@@ -0,0 +1,151 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileRef = void 0;
+exports.file = file;
+const errors_js_1 = require("./errors.js");
+/** Maps common extensions → MIME types accepted by the FlowFlex assets API. */
+const EXT_TO_MIME = {
+    pdf: "application/pdf",
+    doc: "application/msword",
+    docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    xls: "application/vnd.ms-excel",
+    xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    ppt: "application/vnd.ms-powerpoint",
+    pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    txt: "text/plain",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    png: "image/png",
+    mp4: "video/mp4",
+    "3gp": "video/3gpp",
+    aac: "audio/aac",
+    amr: "audio/amr",
+    mp3: "audio/mpeg",
+    ogg: "audio/ogg",
+};
+function inferMimeFromName(name) {
+    const ext = name.split(".").pop()?.toLowerCase();
+    return ext ? EXT_TO_MIME[ext] : undefined;
+}
+function basename(p) {
+    return p.split(/[\\/]/).pop() || p;
+}
+/**
+ * A lazy reference to a file the caller wants to attach to an event. The bytes
+ * are not read until the event is sent. Create one with `FlowFlex.file()` or
+ * the standalone `file()` helper.
+ */
+class FileRef {
+    constructor(source, options = {}) {
+        this.source = source;
+        this.options = options;
+    }
+    /** Resolve the filename, inferring from a path source when possible. */
+    get filename() {
+        if (this.options.filename)
+            return this.options.filename;
+        if (typeof this.source === "string")
+            return basename(this.source);
+        const blobName = this.source?.name;
+        if (blobName)
+            return blobName;
+        throw new errors_js_1.FlowFlexUploadError("Cannot determine filename for attachment — pass { filename } to file()");
+    }
+    /** Resolve the MIME type, inferring from the filename when possible. */
+    get mime() {
+        if (this.options.mime)
+            return this.options.mime;
+        const blobType = this.source?.type;
+        if (blobType)
+            return blobType;
+        const inferred = inferMimeFromName(this.filename);
+        if (inferred)
+            return inferred;
+        throw new errors_js_1.FlowFlexUploadError(`Cannot determine MIME type for "${this.filename}" — pass { mime } to file()`);
+    }
+    get size() {
+        if (typeof this.options.size === "number")
+            return this.options.size;
+        if (this.source instanceof Uint8Array)
+            return this.source.byteLength;
+        if (typeof Blob !== "undefined" && this.source instanceof Blob)
+            return this.source.size;
+        return undefined;
+    }
+    /**
+     * Read the file bytes as a Blob, ready to PUT to storage. On Node a string
+     * source is read from disk via `fs`; Buffers/Uint8Arrays/Blobs are wrapped.
+     */
+    async toBlob() {
+        const { source, mime } = { source: this.source, mime: this.mime };
+        if (typeof source === "string") {
+            // Node-only: read from disk. The indirect specifier + @vite-ignore
+            // stops browser bundlers (Vite/esbuild) from trying to resolve
+            // "fs/promises" at build time — this branch never runs in a browser.
+            let fs;
+            const fsSpecifier = "fs/promises";
+            try {
+                fs = await Promise.resolve(`${fsSpecifier}`).then(s => __importStar(require(s)));
+            }
+            catch {
+                throw new errors_js_1.FlowFlexUploadError("File paths are only supported on Node.js — pass a Blob/File in the browser");
+            }
+            const buf = await fs.readFile(source);
+            return new Blob([new Uint8Array(buf)], { type: mime });
+        }
+        if (typeof Blob !== "undefined" && source instanceof Blob) {
+            return source;
+        }
+        if (source instanceof Uint8Array) {
+            // Covers Buffer too (Buffer extends Uint8Array).
+            return new Blob([source], { type: mime });
+        }
+        throw new errors_js_1.FlowFlexUploadError("Unsupported file source");
+    }
+}
+exports.FileRef = FileRef;
+/**
+ * Wrap a file so it can be attached to an event payload. The SDK uploads it via
+ * a presigned URL when the event is sent and swaps it for its `assetId`.
+ *
+ * @example
+ *   ff.sendEvent("invoice.created", {
+ *     payload: { assetId: file("./invoice.pdf"), customer_id: "cust_123" },
+ *   });
+ */
+function file(source, options) {
+    return new FileRef(source, options);
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { FlowFlex } from "./client.js";
+export { file, FileRef } from "./file.js";
+export type { FileSource } from "./file.js";
+export { FlowFlexError, FlowFlexConfigError, FlowFlexUploadError, } from "./errors.js";
+export type { FlowFlexOptions, FileOptions, SendEventOptions, SendEventResult, UploadUrlResponse, } from "./types.js";
+import { FlowFlex } from "./client.js";
+export default FlowFlex;

package/dist/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlowFlexUploadError = exports.FlowFlexConfigError = exports.FlowFlexError = exports.FileRef = exports.file = exports.FlowFlex = void 0;
+var client_js_1 = require("./client.js");
+Object.defineProperty(exports, "FlowFlex", { enumerable: true, get: function () { return client_js_1.FlowFlex; } });
+var file_js_1 = require("./file.js");
+Object.defineProperty(exports, "file", { enumerable: true, get: function () { return file_js_1.file; } });
+Object.defineProperty(exports, "FileRef", { enumerable: true, get: function () { return file_js_1.FileRef; } });
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "FlowFlexError", { enumerable: true, get: function () { return errors_js_1.FlowFlexError; } });
+Object.defineProperty(exports, "FlowFlexConfigError", { enumerable: true, get: function () { return errors_js_1.FlowFlexConfigError; } });
+Object.defineProperty(exports, "FlowFlexUploadError", { enumerable: true, get: function () { return errors_js_1.FlowFlexUploadError; } });
+const client_js_2 = require("./client.js");
+exports.default = client_js_2.FlowFlex;