flowflex 0.1.0

package/README.md

@@ -0,0 +1,284 @@
+# @fantacode/flowflex
+
+Official Node/browser SDK for firing **FlowFlex custom-integration events** and
+attaching **private files** to them — without ever dealing with presigned URLs,
+Basic-auth headers, or the multi-step upload dance yourself.
+
+```bash
+npm install @fantacode/flowflex
+```
+
+Requires Node 18+ (for the built-in `fetch`) or any modern browser.
+
+---
+
+## Quick start
+
+```ts
+import { FlowFlex } from "@fantacode/flowflex";
+
+const ff = new FlowFlex({
+  apiKey: "cik_xxx",            // from your custom integration
+  apiSecret: "yyy",
+  integrationCode: "ic_abc123", // the code in your event URL: /v1/events/<code>
+  baseUrl: "https://app.flowflex.com",
+});
+
+// Plain event, no file
+await ff.sendEvent("order.placed", {
+  payload: { name: "Ada", order_id: "ord_42" },
+});
+```
+
+In your flow builder, the values land under `trigger` — e.g. `{{trigger.name}}`,
+`{{trigger.order_id}}`.
+
+---
+
+## Attaching a private file
+
+Wrap any file in `ff.file(...)` and drop it into the payload. The SDK uploads it
+through a presigned URL and replaces it with its opaque `assetId` before the
+event is sent. **The file bytes go straight to storage — they never pass through
+the FlowFlex app server.**
+
+```ts
+await ff.sendEvent("invoice.created", {
+  payload: {
+    assetId: ff.file("./invoice.pdf"),  // ← becomes "asset_..." on the wire
+    customer_id: "cust_123",
+  },
+});
+```
+
+Then in your flow's **Media Message** node:
+
+1. Set **File source** → `Private file (assetId)`
+2. Set the **Asset ID** field → `{{trigger.assetId}}`
+
+The key you use in the payload is the key you reference in the flow. If you send
+`{ invoice: ff.file(...) }`, reference it as `{{trigger.invoice}}`.
+
+### Multiple files
+
+A flow can have as many media nodes as you like — put a `file()` anywhere in the
+payload (top-level, nested, or in arrays) and the SDK uploads them **all in
+parallel** and swaps each for its `assetId`. The shape is entirely up to you;
+reference each one by its path in the flow builder.
+
+```ts
+await ff.sendEvent("order.shipped", {
+  payload: {
+    invoice: ff.file("./invoice.pdf"),                 // {{trigger.invoice}}
+    label:   ff.file("./label.png"),                   // {{trigger.label}}
+    gallery: [ff.file("./a.jpg"), ff.file("./b.jpg")], // {{trigger.gallery[0]}}, {{trigger.gallery[1]}}
+    order:   { receipt: ff.file("./receipt.pdf") },    // {{trigger.order.receipt}}
+    note:    "non-file values pass through untouched",
+  },
+});
+// → { invoice: "asset_a", label: "asset_b",
+//     gallery: ["asset_c", "asset_d"],
+//     order: { receipt: "asset_e" }, note: "..." }
+```
+
+`result.uploadedAssets` maps each payload path to its assetId, e.g.
+`{ "invoice": "asset_a", "gallery[0]": "asset_c", "order.receipt": "asset_e" }`.
+
+**Reusing one file across nodes:** if you pass the *same* `file()` instance in
+multiple places, it's uploaded only once and the same `assetId` is used
+everywhere:
+
+```ts
+const banner = ff.file("./banner.png");
+await ff.sendEvent("promo.sent", {
+  payload: { header: banner, footer: banner }, // one upload, same assetId in both
+});
+```
+
+---
+
+## Supplying file bytes other ways
+
+`file()` accepts a path (Node), a `Buffer`/`Uint8Array`, or a `Blob`/`File`
+(browser). When the type can't be inferred, pass `filename` and `mime`:
+
+```ts
+// Buffer / Uint8Array
+ff.file(pdfBuffer, { filename: "invoice.pdf", mime: "application/pdf" });
+
+// Browser File input
+const f = document.querySelector("input[type=file]").files[0];
+ff.file(f); // name + type read from the File
+
+// Override the stored filename
+ff.file("./tmp-7f3a.pdf", { filename: "Invoice-2026.pdf" });
+```
+
+**Allowed types:** PDF, DOC(X), XLS(X), PPT(X), TXT, JPEG, PNG, MP4, 3GPP, AAC,
+AMR, MP3, OGG. **Max size:** 25 MB.
+
+---
+
+## API
+
+### `new FlowFlex(options)`
+
+| Option                    | Type     | Required | Notes                                                                 |
+| ------------------------- | -------- | -------- | --------------------------------------------------------------------- |
+| `apiKey`                  | string   | yes      | Custom-integration key (`cik_…`).                                     |
+| `apiSecret`               | string   | yes      | Custom-integration secret.                                            |
+| `integrationCode`         | string   | yes      | The `<code>` in `/v1/events/<code>`.                                  |
+| `baseUrl`                 | string   | yes      | FlowFlex host. Must be `https` (except `localhost`). Trailing `/api` stripped. |
+| `timeoutMs`               | number   | no       | Per-request timeout. Default `30000`.                                 |
+| `maxFileBytes`            | number   | no       | Client-side size cap. Default `26214400` (25 MB).                     |
+| `fetch`                   | function | no       | Custom fetch for runtimes without a global one.                       |
+
+> **Server-only.** There is no option to run this in a browser — it throws if constructed
+> in one, and browser bundlers resolve it to a stub that throws on import. See **Security**.
+
+### `ff.sendEvent(event, { payload?, idempotencyKey? })`
+
+Uploads any `file()` in `payload`, then POSTs the event. Returns:
+
+```ts
+{
+  response: unknown,                       // raw body from the events endpoint
+  uploadedAssets: Record<string, string>,  // payload path → assetId
+}
+```
+
+An `idempotencyKey` is auto-generated (UUID) if you don't pass one — safe to
+retry the same call.
+
+### `ff.file(source, { filename?, mime?, size? })`
+
+Returns a lazy `FileRef`. Bytes are read only when the event is sent.
+
+### Lower-level helpers
+
+```ts
+const { assetId, uploadUrl } = await ff.createUploadUrl({ filename, mime });
+const assetId = await ff.uploadFile(ff.file("./x.pdf")); // upload, get assetId
+```
+
+---
+
+## Errors
+
+All errors extend `FlowFlexError` (`{ message, status?, code?, details? }`):
+
+- `FlowFlexConfigError` — bad/missing constructor options.
+- `FlowFlexUploadError` — a file couldn't be read or storage rejected it.
+- `FlowFlexError` — API or network failure (`code` is the backend error code,
+  e.g. `MIME_NOT_ALLOWED`, `ASSET_FILE_MISSING`).
+
+```ts
+import { FlowFlexError } from "@fantacode/flowflex";
+
+try {
+  await ff.sendEvent("invoice.created", { payload: { assetId: ff.file("./big.pdf") } });
+} catch (err) {
+  if (err instanceof FlowFlexError) {
+    console.error(err.code, err.status, err.message);
+  }
+}
+```
+
+---
+
+## File lifetime & storage cleanup
+
+> **Important — read before using file attachments in production.**
+
+When you call `ff.file(...)`, the file is uploaded to **private Supabase storage**
+that only the FlowFlex backend can read. It is **not** a public URL and the caller
+cannot access it after upload.
+
+### How long does the file stay?
+
+| Phase | Duration |
+| ----- | -------- |
+| Presigned upload URL valid | **2 hours** from `createUploadUrl` |
+| File kept in storage | **48 hours** from upload |
+| After 48 hours | File **deleted from storage** + record removed |
+
+After the flow delivers the WhatsApp message the file is no longer needed. The
+backend runs an automatic cleanup job every hour that:
+
+1. Finds assets whose 48-hour window has expired
+2. **Deletes the file from Supabase storage first**
+3. Then removes the database record
+
+This means storage never accumulates — every file is cleaned up within ~1 hour
+of its expiry.
+
+### What this means for you
+
+- **Do not store `assetId` long-term** expecting to reuse it. It expires in 48h.
+- **Each event send should get a fresh `assetId`** by calling `ff.sendEvent` with
+  a new `ff.file(...)`. The SDK handles the upload automatically.
+- If you fire the event more than 48h after uploading, the file will be gone and
+  the flow will fail with `ASSET_FILE_MISSING`. Keep your event send close to
+  the upload.
+- **Re-sending the same message** to a different recipient after 48h requires a
+  fresh upload — call `sendEvent` again with the file, don't reuse the old assetId.
+
+### Typical correct pattern
+
+```ts
+// ✅ Upload + fire in the same operation — always fresh
+await ff.sendEvent("invoice.created", {
+  payload: { assetId: ff.file("./invoice.pdf") },
+});
+
+// ❌ Don't store assetId and reuse it hours later
+const { uploadedAssets } = await ff.sendEvent(...);
+// ... 50 hours later ...
+// uploadedAssets["assetId"] is now expired and deleted
+```
+
+---
+
+## Security
+
+**This SDK is server-only.** Your `apiKey`/`apiSecret` are integration-wide
+credentials. Bundling them into front-end code exposes them to anyone who opens
+devtools — they could then fire events and upload files as you. The browser is
+hard-blocked, with no opt-out:
+
+- **Runtime** — the constructor **always throws** if it detects a browser.
+- **Bundle time** — browser bundlers (webpack / Vite / Next) resolve the package to
+  a stub (via the `"browser"` export condition) that **throws on import**, so the SDK
+  can't be built into client code in the first place.
+
+Other protections built in:
+
+- **HTTPS enforced.** `baseUrl` must be `https://` (only `localhost` may use
+  `http`), so Basic-auth credentials are never sent in cleartext.
+- **No credential leakage.** The `Authorization` header is never included in
+  error messages, logs, or `FlowFlexError.details`.
+- **Header-injection safe.** The `event` name and `idempotencyKey` are rejected
+  if they contain control characters (CRLF).
+- **Path-injection safe.** `integrationCode` is URL-encoded into the request path.
+- **Prototype-pollution safe.** Payload keys like `__proto__` can't pollute
+  `Object.prototype` during the file-swap walk.
+- **Per-request timeouts** (default 30 s) on every network call.
+- **Client-side size cap** (default 25 MB) so oversized files fail before upload.
+
+If you must call FlowFlex from a browser, proxy through your own backend: the
+browser talks to your server, your server holds the secret and calls this SDK.
+
+## How it works
+
+```
+ff.sendEvent("invoice.created", { payload: { assetId: file("invoice.pdf") } })
+        │
+        ├─ 1. POST /v1/assets/upload-url   → { assetId, uploadUrl }
+        ├─ 2. PUT  <uploadUrl>  (file bytes straight to private storage)
+        └─ 3. POST /v1/events/<code>  with { assetId: "asset_…" }
+                 │
+                 └─ flow runs; media node resolves assetId → WhatsApp media at send time
+```
+
+The caller only ever holds the opaque `assetId`. There is no readable link to
+the file — the backend resolves it server-side when the flow delivers the message.

package/dist/browser.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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.
+ */
+export declare class FlowFlexError extends Error {
+    constructor(message?: string);
+}
+export declare class FlowFlexConfigError extends FlowFlexError {
+}
+export declare class FlowFlexUploadError extends FlowFlexError {
+}
+export declare class FlowFlex {
+    constructor();
+}
+export declare class FileRef {
+    constructor();
+}
+export declare function file(): never;
+export default FlowFlex;

package/dist/browser.js

@@ -0,0 +1,52 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileRef = exports.FlowFlex = exports.FlowFlexUploadError = exports.FlowFlexConfigError = exports.FlowFlexError = void 0;
+exports.file = file;
+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.";
+class FlowFlexError extends Error {
+    constructor(message = MESSAGE) {
+        super(message);
+        this.name = "FlowFlexError";
+    }
+}
+exports.FlowFlexError = FlowFlexError;
+class FlowFlexConfigError extends FlowFlexError {
+}
+exports.FlowFlexConfigError = FlowFlexConfigError;
+class FlowFlexUploadError extends FlowFlexError {
+}
+exports.FlowFlexUploadError = FlowFlexUploadError;
+class FlowFlex {
+    constructor() {
+        throw new FlowFlexConfigError(MESSAGE);
+    }
+}
+exports.FlowFlex = FlowFlex;
+class FileRef {
+    constructor() {
+        throw new FlowFlexConfigError(MESSAGE);
+    }
+}
+exports.FileRef = FileRef;
+function file() {
+    throw new FlowFlexConfigError(MESSAGE);
+}
+exports.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);

package/dist/client.d.ts

@@ -0,0 +1,55 @@
+import { FlowFlexOptions, SendEventOptions, SendEventResult, UploadUrlResponse, FileOptions } from "./types.js";
+import { FileRef, FileSource } from "./file.js";
+export declare class FlowFlex {
+    private readonly apiKey;
+    private readonly apiSecret;
+    private readonly integrationCode;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    private readonly maxFileBytes;
+    constructor(options: FlowFlexOptions);
+    /** Convenience re-export so callers can do `ff.file(...)`. */
+    file(source: FileSource, options?: FileOptions): FileRef;
+    private authHeader;
+    /** fetch wrapper with timeout + JSON parsing + error normalization. */
+    private request;
+    /**
+     * Request a presigned upload URL. Most callers don't need this directly —
+     * use `file()` inside an event payload and let `sendEvent` handle uploads.
+     */
+    createUploadUrl(input: {
+        filename: string;
+        mime: string;
+        size?: number;
+    }): Promise<UploadUrlResponse>;
+    /** Upload one FileRef and return its assetId. */
+    uploadFile(ref: FileRef): Promise<string>;
+    /**
+     * 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.
+     */
+    private cloneAndCollect;
+    /**
+     * 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.
+     */
+    private resolveFiles;
+    /**
+     * 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" },
+     *   });
+     */
+    sendEvent(event: string, body?: {
+        payload?: Record<string, unknown>;
+    } & SendEventOptions): Promise<SendEventResult>;
+}